From e81bd8003195371bff78e978c45ae5f5d451453c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 28 Jul 2026 02:20:39 +0000 Subject: [PATCH] Document Promptkit development and releases --- README.md | 19 +++++- docs/development.md | 141 +++++++++++++++++++++++++++++++++++--------- docs/release.md | 137 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 266 insertions(+), 31 deletions(-) create mode 100644 docs/release.md diff --git a/README.md b/README.md index 8502357..5186c61 100644 --- a/README.md +++ b/README.md @@ -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). diff --git a/docs/development.md b/docs/development.md index 3fee502..1ae4fcb 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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. \ No newline at end of file +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. diff --git a/docs/release.md b/docs/release.md new file mode 100644 index 0000000..5c649dd --- /dev/null +++ b/docs/release.md @@ -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.