eric/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document Promptkit development and releases

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 02:20:39 +00:00
parent 120c6db67a
commit e81bd80031
3 changed files with 266 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

19
README.md
View File

@@ -1,3 +1,18 @@
# PromptKit
# Promptkit
TODO
Promptkit is the reusable Go prompt-execution framework being separated from
Scriptorium. Its module path is:
```text
gitea.maximumdirect.net/eric/promptkit
```
The repository currently provides the independent Go module and its root public
package boundary. Framework behavior and consumer APIs have not yet been
extracted, so there is no installation or usage example at this time.
Contributors should start with the [development guide](docs/development.md).
The [architecture policy](docs/policy/architecture.md) defines the library
boundary and constraints that future framework work must preserve.
Promptkit is licensed under the [GNU General Public License version 3](LICENSE).

141
docs/development.md
View File

@@ -1,54 +1,137 @@
# Development
This is the contributor entry point for thsi application. Use the task-specific
reading guide below before making changes. Canonical architecture, contracts,
component behavior, and policies remain in their owning documents.
This is the contributor entry point for Promptkit, a reusable Go library. All
contributors must read the
[architecture policy](policy/architecture.md) before making changes.
## Initial Orientation
Before starting work:
1. inspect the working tree and preserve unrelated changes;
2. read the architecture policy for code or design work;
3. read the policy, contract, and internal documents listed for the task;
4. inspect the relevant implementation and tests before deciding how to change
them.
2. read the policy, contract, and internal documents listed for the task;
3. inspect the relevant implementation and tests before deciding how to change
them; and
4. keep documentation limited to implemented behavior unless an accepted
decision or temporary roadmap explicitly owns future work.
Start with:
- [Architecture policy](policy/architecture.md) for system boundaries,
invariants, and non-goals;
- [Internal component overview](internal/overview.md) for the current package
and component map;
- [Documentation policy](policy/documentation.md) before changing
- the [architecture policy](policy/architecture.md) for library boundaries,
dependency direction, invariants, and non-goals;
- the [internal component overview](internal/overview.md) for the current
package and component inventory;
- the [documentation policy](policy/documentation.md) before changing
documentation;
- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
tests.
- the [testing policy](policy/testing.md) before adding, rewriting, or deleting
tests; and
- the [release procedure](release.md) for version and publication work.
## Task-Specific Reading Guide
| Task | Read before changing |
| --- | --- |
| Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under `examples/` |
| Architecture decisions or future work | The [documentation policy](policy/documentation.md) and relevant accepted ADRs |
| Documentation or examples | The [documentation policy](policy/documentation.md) and the canonical owner of the affected contract. |
| Tests or test fixtures | The [testing policy](policy/testing.md), the owning package, and any focused internal document listed by the component overview. |
| Root public API, once implemented | The [architecture policy](policy/architecture.md), [root package declaration](../doc.go), [testing policy](policy/testing.md), and existing GoDoc. |
| Internal package implementation, once introduced | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and any focused internal document that the overview lists for that package. |
| Integration behavior, once introduced | The [architecture policy](policy/architecture.md), [documentation policy](policy/documentation.md), and the integration's owning contract under `docs/integrations/`. |
| Release preparation or publication | The [release procedure](release.md). |
For cross-cutting changes, follow every applicable row. Internal component
documents own detailed subsystem change recipes.
For cross-cutting changes, follow every applicable row. Do not create
placeholder documents for packages, APIs, or integrations that do not yet
exist.
## Baseline Validation
## Maintainer-Run Validation
Use focused checks while iterating, then run validation proportionate to the
change and the risks described by the testing policy.
Promptkit does not currently use hosted CI. Maintainers are responsible for
running the documented checks before accepting changes. Run the default Go
validation from the Promptkit repository root:
The repository-level baseline for code changes is:
```bash
```sh
go test ./...
go vet ./...
go build ./cmd/scriptorium
go build ./...
```
Documentation-only work does not require the full Go suite unless it changes
commands, examples, generated output, or another behavior that the suite
validates. Always check changed links, paths, examples, and canonical ownership.
Check formatting across every tracked Go file:
```sh
gofmt -l $(git ls-files '*.go')
```
The formatting command must produce no paths. Follow every added or changed
Markdown link and confirm its target exists. Finally, check whitespace:
```sh
git diff --check
```
Documentation-only work does not require unrelated new tests, but it still
requires link validation and `git diff --check`. Run the Go validation whenever
documentation changes commands, examples, generated output, or another
behavior checked by the module.
## Focused Validation
Use focused checks while iterating, then run the complete validation sequence
before accepting the change. The root package currently supports:
```sh
go test .
go vet .
go build .
```
Filter tests by name without assuming a future package layout:
```sh
go test ./... -run 'TestName'
```
Replace `TestName` with a useful regular expression. When internal packages are
introduced, target only paths that actually exist, such as
`go test ./path/to/package`, and consult the internal component overview for
their owning documentation. A filtered or package-specific run does not replace
the complete repository validation.
## Coordinated Work With Scriptorium
Promptkit and Scriptorium must remain independently valid. For temporary local
integration, use either a Go workspace outside both repositories or an
uncommitted replacement in the consuming module.
If the repositories are sibling directories, run the workspace commands from
their parent directory:
```sh
go work init ./promptkit ./scriptorium
go work sync
```
Use the workspace only for coordinated local checks. From the same parent
directory, remove it when finished:
```sh
rm -f go.work go.work.sum
```
Alternatively, from the Scriptorium repository root, temporarily point its
Promptkit dependency at the sibling checkout:
```sh
go mod edit -replace gitea.maximumdirect.net/eric/promptkit=../promptkit
```
After coordinated checks, remove the replacement and reconcile module
metadata:
```sh
go mod edit -dropreplace gitea.maximumdirect.net/eric/promptkit
go mod tidy
```
Never commit `go.work`, `go.work.sum`, or a local filesystem `replace`
directive. Before committing in either repository, inspect its module files and
working tree independently. Published consumer versions must depend on a tagged
Promptkit version, not a workspace, local replacement, or unpublished commit.

137
docs/release.md Normal file
View File

@@ -0,0 +1,137 @@
# Release Procedure
## Release Model
Promptkit publishes a Go library through source commits and semantic Go module
tags. It does not publish runnable binaries or binary packages and does not
currently use hosted CI. The release maintainer performs and records the
required validation.
The first planned release is `v0.1.0`. Do not create that tag until the
framework has been extracted and the resulting public library has passed this
procedure. Later tags use the `vMAJOR.MINOR.PATCH` form. While Promptkit remains
pre-`v1`, release notes must identify intentional public API changes and any
consumer migration required by them.
## Prepare The Release
Work from a clean checkout of the intended release commit, outside any Go
workspace and without a local module replacement. Confirm the source commit is
already published through the normal branch workflow.
From the Promptkit repository root, verify the checkout:
```sh
test -z "$(go env GOWORK)"
test -z "$(git status --short)"
git fetch --tags origin
```
Confirm the module and root package metadata:
```sh
go list -m -f '{{.Path}} {{.GoVersion}}'
go list -f '{{.Name}} {{.ImportPath}}' .
```
The output must be:
```text
gitea.maximumdirect.net/eric/promptkit 1.25.5
promptkit gitea.maximumdirect.net/eric/promptkit
```
Run the same default Go validation required by the
[development guide](development.md):
```sh
go test ./...
go vet ./...
go build ./...
```
Check every tracked Go file and repository whitespace:
```sh
gofmt -l $(git ls-files '*.go')
git diff --check
```
The formatting command must produce no paths. Follow every maintained Markdown
link and confirm its target exists. Review the repository for generated
binaries, test or coverage output, credentials, template residue, and other
files that do not belong in source control.
Confirm that no workspace override is tracked and that `go.mod` contains no
`replace` directive:
```sh
git ls-files go.work go.work.sum
rg -n '^replace\b' go.mod
```
Both commands must produce no output. Re-run `git status --short` and require a
clean result after every validation and review check.
## Create And Publish The Tag
Choose the semantic version from the intended compatibility change. Record the
release commit before tagging:
```sh
release_version=v0.1.0
release_commit=$(git rev-parse HEAD)
```
Replace the example version for later releases and keep both values in the same
shell for the remaining commands. Confirm the tag does not already exist
locally or remotely:
```sh
test -z "$(git tag --list "$release_version")"
test -z "$(git ls-remote --tags origin "refs/tags/$release_version")"
```
Create an annotated tag whose message identifies the release and records that
the documented validation passed for the tagged commit:
```sh
git tag --annotate "$release_version" \
--message "Promptkit $release_version; documented validation passed for $release_commit"
```
Inspect the tag before publication:
```sh
git show --no-patch --decorate "$release_version"
test "$(git rev-list -n 1 "$release_version")" = "$release_commit"
```
Publish the tag without relying on a hosting-provider-specific release
interface:
```sh
git push origin "refs/tags/$release_version"
```
## Verify Publication
Confirm that the remote tag object matches the local annotated tag and still
resolves to the intended source commit:
```sh
remote_tag=$(git ls-remote --tags origin "refs/tags/$release_version" | awk '{print $1}')
test "$remote_tag" = "$(git rev-parse "refs/tags/$release_version")"
test "$(git rev-list -n 1 "refs/tags/$release_version")" = "$release_commit"
```
Promptkit must publish the required tag before Scriptorium or another consumer
publishes a release that depends on that version. Released consumer modules
must not use a local replacement or unpublished Promptkit revision.
## Policy Changes
Document and approve a durable policy change before introducing hosted
automation, binary artifacts, or different release governance. Update this
procedure in the same change so maintainers do not rely on hidden release
requirements.