Document Promptkit development and releases

2026-07-28 02:20:39 +00:00
parent 120c6db67a
commit e81bd80031
3 changed files with 266 additions and 31 deletions
--- 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.
+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.
--- a/docs/release.md
+++ 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.