base-layer/commandkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Reconcile module docs and release materials

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-11 02:06:06 +00:00
parent 18e81a5579
commit d2b5b0f3a8
45 changed files with 2380 additions and 362 deletions
Download Patch File Download Diff File Expand all files Collapse all files

221
docs/release.md
View File

@@ -1,47 +1,46 @@
# CommandKit release procedure
## Scope and prerequisites
## Scope and release order
CommandKit publishes source-only Go module releases: an immutable annotated
version tag for one committed candidate and its matching checked-in release
note. This procedure does not publish a hosted release page, binaries,
checksums, or other delivery assets, and it requires no delivery credentials.
CommandKit publishes source-only Go module releases. Each module has an
independent version and immutable annotated tag. This procedure publishes no
hosted release page, binaries, checksums, or other delivery assets. A successful
source-tag push is release completion; CI, module proxy availability, and
consumer installation are not completion gates.
Use branch `main`, remote `origin`, and the expected effective push endpoint
`https://gitea.maximumdirect.net/eric/CommandKit.git`. The profile enforces that
endpoint during publication. The maintainer needs the selected
[release toolchain](#release-toolchain), Git with push access to `origin`, and a
POSIX shell.
Publish in dependency order: core, then `ckconfig`, then `ckprompt`. The
integration modules require the preceding CommandKit releases, so prepare and
publish each module only after its CommandKit dependencies are available. A root
release runs only the root module's default suite; it need not run suites for
independently released integrations.
This procedure follows the [release policy](policy/release.md); the release-note
footer follows the [OSS discoverability policy](policy/oss.md#discoverability).
Use branch `main`, remote `origin`, and expected effective push endpoint
`https://gitea.maximumdirect.net/eric/CommandKit.git`. The selected module profile
enforces the endpoint. The maintainer needs the selected
[release toolchain](#release-toolchain), Git push access, and a POSIX shell.
This procedure follows the [release policy](policy/release.md); release-note
footers follow the [OSS discoverability policy](policy/oss.md#discoverability).
ReleaseKit v0.3.0 owns candidate validation, publication guards, annotated tag
creation, tag publication, and outcome reporting. The repository profile selects
only its default candidate suite. The launcher bootstraps the module-selected
native executable into ignored `.releasekit/` storage and invokes its `publish`
command. The upstream [CLI reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/cli.md),
[profile reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/config.md),
and [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/consumers/publish.md)
own detailed command, profile, and status contracts.
ReleaseKit v0.4.0 owns candidate validation, publication guards, tag creation,
tag publication, and outcome reporting. Its pinned public contracts are the
[CLI reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/b96262eb0ce9c8f2eb3e948a5841db2b799bc91b/docs/cli.md),
[profile reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/b96262eb0ce9c8f2eb3e948a5841db2b799bc91b/docs/config.md),
and [publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/b96262eb0ce9c8f2eb3e948a5841db2b799bc91b/docs/consumers/publish.md).
The repository selects one default module suite per invocation. The launcher
bootstraps the native tool into ignored `.releasekit/` storage and delegates to
its `publish` command.
## Release toolchain
The selected release toolchain is **Go 1.26.8**. The consumer minimum is
**Go 1.26.0**; validation uses a later patch within that supported Go series.
The [consumer guide](consumers/guide.md#go-compatibility) explains the minimum and
its shared tool-module requirement; the
[release policy](policy/release.md#consumer-minimum-and-release-toolchain) governs
changes to either selection.
The selected release toolchain is **Go 1.26.8**. Each module declares a consumer
minimum of **Go 1.26.0**. Maintainers use Go 1.26.8 for dependency preparation,
candidate validation, and the ReleaseKit bootstrap. The
[consumer guide](consumers/guide.md#go-compatibility) and
[release policy](policy/release.md#consumer-minimum-and-release-toolchain)
describe these selections.
Use this toolchain for candidate validation and the native ReleaseKit bootstrap,
including CI jobs that perform those tasks. The launcher and ReleaseKit invoke
`go` from `PATH` with `GOTOOLCHAIN=local`, so select that installation in the
shell used for preparation and publication.
If it is not installed, use the [standard Go installation method](https://go.dev/doc/manage-install).
Ensure Go's executable installation directory (`GOBIN`, or `GOPATH/bin` by
default) is on `PATH` so the downloaded-version wrapper can be invoked:
Select Go 1.26.8 on `PATH`; the launcher uses `GOTOOLCHAIN=local`. If needed,
install it with the standard Go tools:
```sh
GOWORK=off GOTOOLCHAIN=local go install golang.org/dl/go1.26.8@latest
@@ -51,115 +50,75 @@ hash -r
GOWORK=off GOTOOLCHAIN=local go version
```
The final command should identify Go 1.26.8. An existing Go 1.26.8 installation
may be selected directly on `PATH` instead. Toolchain installation and dependency
preparation precede the offline publication checks; they add no validation pass.
## Modules, versions, notes, and shared files
## Prepare and publish a candidate
Select exactly one module with the launcher:
Choose a fresh, unused stable Semantic Version tag in the form
`vMAJOR.MINOR.PATCH`, with no leading zeroes. Before `v1.0.0`, a minor release
may change a documented contract if its note explains the impact and consumer
action; a patch release must not intentionally break contracts within its
minor line. Never reuse a version previously published through any release
channel. The first version is selected during release preparation, not embedded
in the tool or profile.
| Selector | Physical module directory | Release note | Full tag | Shared project files |
| --- | --- | --- | --- | --- |
| `core` | repository root | `docs/releases/<version>.md` | `<version>` | root `COPYRIGHT`, `LICENSE`, `docs/oss/attribution.md` |
| `ckconfig` | `integrations/ckconfig` | `integrations/ckconfig/docs/releases/<version>.md` | `integrations/ckconfig/<version>` | that module's `COPYRIGHT`, `LICENSE`, `docs/oss/attribution.md` |
| `ckprompt` | `integrations/ckprompt` | `integrations/ckprompt/docs/releases/<version>.md` | `integrations/ckprompt/<version>` | that module's `COPYRIGHT`, `LICENSE`, `docs/oss/attribution.md` |
Start from `main` and prepare a note at `docs/releases/<version>.md`. Begin with
a heading containing `CommandKit` and the exact version. Include a useful
summary and any compatibility impact or upgrade instructions. End it with the
license and attribution links at that version's immutable source tag, replacing
`VERSION` with the selected tag:
Use a fresh stable semantic version (`vMAJOR.MINOR.PATCH`) for the selected
module. Before `v1.0.0`, a minor release may change a documented contract when
its note explains the impact and consumer action. Never reuse a published
version. Each release note starts with a product title and exact version, gives
a proportionate summary and compatibility guidance, and ends with immutable
links to that module's local grant, license, and attribution paths. The full tag
in each URL includes the integration directory where applicable. Future tag
URLs need not resolve before publication.
```markdown
[COPYRIGHT](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/LICENSE) |
[ATTRIBUTION](https://gitea.maximumdirect.net/eric/CommandKit/src/tag/VERSION/docs/oss/attribution.md)
```
Root publication validates root shared files. Integration publication validates
the matching module-local files; it does not substitute root-only notices. The
module release profiles select their physical module directory while using the
same repository and publication endpoint.
Review these paths in the candidate; the future tag URLs do not need to resolve
before publication.
## Prepare and publish one candidate
Prepare dependencies separately from the offline candidate suite:
Prepare dependencies in the selected module before the candidate is finalized.
Do this after the preceding CommandKit module has been published and before the
selected candidate suite is run. For `core`, run the command at the repository
root; for integrations, run it from that module directory. Commit any resulting
`go.mod` or `go.sum` changes with the release candidate. The sum files must
reflect dependencies actually downloaded for that module; do not fabricate
future sums.
Run these commands in the same shell session so the version variable remains
set:
```sh
commandkit_version=vX.Y.Z
GOWORK=off GOTOOLCHAIN=local go mod download
```
If dependency preparation changes `go.mod` or `go.sum`, review and commit those
changes with the candidate. Commit the note and all candidate changes on `main`,
then publish that commit to `origin`:
Then commit the selected module's release note and all intended candidate
changes on `main`, and publish the candidate commit to `origin`. Set one
selector, module directory, and version from the table above, then run:
```sh
module_dir=.
module_selector=core
module_version=v0.2.0
(cd "$module_dir" && GOWORK=off GOTOOLCHAIN=local go mod download)
# Commit reviewed dependency changes and the selected module's note on main.
git push origin HEAD:refs/heads/main
./scripts/release "$commandkit_version"
./scripts/release "$module_selector" "$module_version"
```
The launcher builds the ReleaseKit version selected by the module in readonly
mode. After preflight, `publish` runs the offline default Go suite once, checks
the candidate and remote guards, creates an annotated tag from the committed
note, and pushes only that tag object. The launcher does not push `main`; push
the candidate first. `check` is available for optional diagnosis and is not a
required step before `publish`. The automated publication workflow runs the
final-candidate suite once; configured additional checks should avoid duplicating
that suite. Maintainers may rerun diagnostics when useful. Successful source
publication does not wait for CI, module availability, or consumer installation.
Run only the command for the selected module. Its profile runs the complete
offline deterministic default suite once for that module, checks candidate and
remote guards, creates the annotated tag from the matching note, and pushes
only that full tag. `check` is available for diagnosis and is not a required
pre-publication command. The launcher does not push `main`; publish the
candidate commit first. Successful source publication does not wait for CI,
proxy availability, or downstream installation.
## Completion and statuses
## Completion and ambiguous publication
Publication is complete when the intended annotated tag is successfully pushed
to the expected endpoint, or when an exact tag-object query confirms that push
after an error. Status 0 reports confirmed publication. Status 1 reports a
known failure or conflict; status 2 reports invalid input or profile; status 3
means the push outcome remains unresolved. See the upstream [CLI status
contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/e43df4416e0ed987349b2ea04a2c68c25e552772/docs/cli.md).
A successful push to the expected endpoint completes the source release. On an
ambiguous result, use the exact endpoint, full tag, and annotated tag object
reported by that invocation. Confirm endpoint resolution has not changed, then
query only that exact tag ref. Compare the remote annotated tag-object ID with
the reported object: an exact match confirms publication, a different object is
a conflict, successful output without the ref proves absence at that endpoint,
and a failed query leaves the result unresolved. Do not infer the captured
endpoint's state from another remote or a rewritten URL.
For a failed or ambiguous push, use the exact endpoint, version, and annotated
tag object reported by the invocation. Confirm that Git still resolves the
captured endpoint to itself before querying only that tag ref:
```sh
releasekit_endpoint='COPY THE CAPTURED ENDPOINT EXACTLY'
releasekit_version='vX.Y.Z'
releasekit_tag_object='COPY THE REPORTED TAG OBJECT ID'
releasekit_ref="refs/tags/$releasekit_version"
releasekit_resolved_endpoint=$(git ls-remote --get-url -- "$releasekit_endpoint") || {
printf '%s\n' 'publication state is unresolved: endpoint resolution failed' >&2
exit 1
}
if [ "$releasekit_resolved_endpoint" != "$releasekit_endpoint" ]; then
printf '%s\n' 'publication state is unresolved: endpoint resolution changed' >&2
exit 1
fi
releasekit_remote_tag=$(git ls-remote --refs -- "$releasekit_endpoint" "$releasekit_ref") || {
printf '%s\n' 'publication state is unresolved: remote query failed' >&2
exit 1
}
printf '%s\n' "$releasekit_remote_tag"
```
`--refs` returns the annotated tag object's ID, not its peeled commit. Compare
that ID with `releasekit_tag_object`: an exact match confirms publication; a
different object is a conflict; successful output with no matching ref proves
absence at the captured endpoint. A failed query or changed URL resolution is
unresolved, never evidence of absence. Do not query a different fetch URL or
follow a rewritten endpoint to infer the captured destination's state.
ReleaseKit retains a local tag after a failed push, so the tag blocks an ordinary
retry. After proving the tag absent at the captured endpoint,
confirm that it was never published or used by another release channel before
deliberately removing the unpublished local tag:
```sh
git tag -d "$releasekit_version"
```
Do not move, overwrite, recreate, or delete a published tag. If the exact tag
object is present remotely, keep it. Resolve conflicts with a fresh version;
corrections to published source require a new version. A transport failure
alone does not require a new version.
ReleaseKit may retain a local tag after a failed push. Remove an unpublished
local tag only after proving absence at the captured endpoint and confirming
that the tag was never published or used by another release channel. Never
move, overwrite, recreate, or delete a published tag. Resolve conflicts with a
fresh version; corrections to published source require a new version.