Write release notes and migration guidance for v0.4.0
This commit is contained in:
141
docs/releases/v0.4.0.md
Normal file
141
docs/releases/v0.4.0.md
Normal file
@@ -0,0 +1,141 @@
|
||||
# ReleaseKit v0.4.0
|
||||
|
||||
## Summary
|
||||
|
||||
ReleaseKit supports releasing individual Go modules within a repository, with
|
||||
module-specific validation, builds, tags, and Gitea release pages. Root-module
|
||||
consumers retain the simple default configuration. This release also improves
|
||||
path resolution, offline source inspection, failure diagnostics, and efficiency.
|
||||
|
||||
## Changes
|
||||
|
||||
- `Check`, `Publish`, `Build`, and `Deliver` accept `ModuleDir` and expose the
|
||||
resolved module directory, declared module path, and complete tag in their
|
||||
results. Each operation resolves its module identity once. Product commands
|
||||
receive repository and module context, and candidate callbacks receive module
|
||||
identity.
|
||||
- Release tags follow the selected module's physical location and declared major
|
||||
version. For example, `v2.1.0` for
|
||||
`example.com/project/integrations/core/v2` uses
|
||||
`integrations/core/v2.1.0` whether its physical directory is
|
||||
`integrations/core` or `integrations/core/v2`. Its note remains at that physical
|
||||
module's `docs/releases/v2.1.0.md`. Binary version output and asset names retain
|
||||
the semantic version; Git publication and Gitea delivery use the complete tag.
|
||||
- Profiles add `module_dir`. Go checks and configured product commands run from
|
||||
the selected module. Automatic committed-file inputs stop at independent
|
||||
nested modules; vendored files remain included. Nested fixtures remain
|
||||
available to the parent module's product tests.
|
||||
- `ValidationSpec.SharedFiles` and profile `validation.shared_files` select
|
||||
repository-relative literal files for optional file checks. Omission selects
|
||||
the available root copyright, license, and attribution defaults; an explicit
|
||||
list replaces them, and an explicit empty list selects none. Explicit files
|
||||
must exist even with checks disabled. Selection preserves the enabled checks
|
||||
and Go test scope; reference inspection can read destinations elsewhere in
|
||||
the captured repository.
|
||||
- Module releases receive separate Gitea pages, including source-only modules.
|
||||
Relative build output and prebuilt delivery paths share the selected module
|
||||
as their base. Prebuilt receipts bind artifacts to module identity, semantic
|
||||
version, complete tag, source commit, and normalized build settings.
|
||||
- `ci-deliver` accepts the complete event tag. Prepared mode verifies a checkout
|
||||
already detached at that tag, and expected-module and expected-tag checks bind
|
||||
delivery to the CI selection before building or contacting Gitea. The
|
||||
multi-module example shares a module map between its local launcher and
|
||||
Woodpecker workflow. The workflow verifies the tag before reading the mapping,
|
||||
profile, or tool selection, preserving the tagged configuration for retries.
|
||||
|
||||
## Reliability and efficiency
|
||||
|
||||
- Operations resolve the containing Git checkout root when invoked from a child
|
||||
directory. Working-tree and committed module paths resolve symlinks consistently,
|
||||
including paths containing `..`. Committed identity comes from Git objects;
|
||||
page-only delivery can use committed module metadata absent from the worktree.
|
||||
Valid local main-module paths are accepted.
|
||||
- Build failures preserve available identity and settings alongside completed
|
||||
artifacts. Invalid versions retain the public error identity and the CLI's
|
||||
usage-error status. Prebuilt delivery accepts equivalent checkout paths while
|
||||
retaining source and module verification.
|
||||
- Committed release-note and validation reads remain offline in partial clones.
|
||||
Validation reads blob contents and sizes as needed for selected inputs and
|
||||
referenced destinations. Unavailable blobs outside that inspection scope do
|
||||
not prevent applicable checks.
|
||||
- Module-file selection uses ancestor boundary lookups. Operations reuse Go
|
||||
environment discovery while its inputs remain suitable for reuse and acquire
|
||||
Go settings only when Go work needs them. Delivery reuses its local asset
|
||||
verification when uploading missing assets, removing a repeated hashing pass.
|
||||
|
||||
These improvements depend on the repository and workload. Artifact verification,
|
||||
exact remote comparisons, additive retries, and partial-delivery reporting retain
|
||||
their behavior.
|
||||
|
||||
## Compatibility
|
||||
|
||||
This pre-1.0 minor release introduces a clean API and receipt cutover:
|
||||
|
||||
- `TaggedCheckoutRequest.Version` becomes `Tag`, containing the complete Git
|
||||
tag. `VerifyOnly` adds verification of an already prepared checkout.
|
||||
- `PrepareBuildDependencies` now accepts `DependencyPreparationRequest` with
|
||||
repository and module directories.
|
||||
- The private build receipt requires schema version 1 and module identity.
|
||||
Existing receipts must be regenerated before prebuilt delivery.
|
||||
- Root-module committed-file checks exclude independent nested modules. Select
|
||||
those modules separately when their files need release validation.
|
||||
|
||||
The Go minimum remains 1.26.0. Root-module releases retain their existing note
|
||||
path, unprefixed tags, profile defaults, and ordinary workflow without a module
|
||||
map. The root orchestration facade and separate lightweight `buildinfo` facade
|
||||
retain their roles; runtime version access requires no migration.
|
||||
|
||||
Source-tag publication remains the source-release completion point. Hosted page
|
||||
and asset delivery remains asynchronous and can be retried from the same
|
||||
immutable tag. ReleaseKit's deliverables remain its source tag and hosted note
|
||||
page.
|
||||
|
||||
## Upgrade guidance
|
||||
|
||||
1. Select v0.4.0 in each consumer module that uses ReleaseKit. For API consumers:
|
||||
|
||||
```sh
|
||||
go get gitea.maximumdirect.net/eric/ReleaseKit@v0.4.0
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
For consumers using the CLI as a Go tool dependency:
|
||||
|
||||
```sh
|
||||
go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.4.0
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
Review and commit the resulting module and checksum changes together with
|
||||
caller, profile, and workflow updates. Keep historical tag retries paired
|
||||
with the tool and workflow recorded at that tag.
|
||||
|
||||
2. Update preparation API calls for `Tag` and `DependencyPreparationRequest`.
|
||||
For nested modules, set `ModuleDir` or profile `module_dir` to the physical
|
||||
module location, with its own `go.mod` declaration. Keep ordinary `Version`
|
||||
arguments as semantic versions. Use result `ModuleDir`, `ModulePath`, and
|
||||
`Tag` where module identity is needed. Product commands can distinguish their
|
||||
contexts through `RELEASEKIT_REPOSITORY_DIR` and `RELEASEKIT_MODULE_DIR`.
|
||||
|
||||
3. Update `ci-deliver` invocations to pass the full event tag and required
|
||||
`--commit OID`. Use `--prepared` after bootstrap verification and
|
||||
`--expected-module DIR` for mapped launchers. Prepare and commit each binary
|
||||
module's checksums before tagging so dependency preparation leaves tagged
|
||||
source clean. Root-only consumers can retain the ordinary tag workflow.
|
||||
|
||||
4. Rebuild existing prebuilt outputs with the v0.4.0 `build` command before
|
||||
`deliver --assets DIR`. Relative output and asset paths both resolve from the
|
||||
selected module. Review optional shared-file selections and nested-module
|
||||
validation coverage, then run the consumer's ordinary checks.
|
||||
|
||||
See the
|
||||
[adoption guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/consumers/adoption.md),
|
||||
[configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/config.md),
|
||||
[CLI contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/cli.md),
|
||||
[delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/consumers/delivery.md),
|
||||
and [multi-module example](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/examples/multi-module/README.md)
|
||||
for supported usage.
|
||||
|
||||
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/COPYRIGHT) |
|
||||
[LICENSE](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/LICENSE) |
|
||||
[ATTRIBUTION](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/oss/attribution.md)
|
||||
@@ -733,8 +733,8 @@ evidence describe the complete implemented feature.
|
||||
owners. Explain module selection, semantic version versus full tag, declared
|
||||
versus physical module identity, note/source/license links, path bases,
|
||||
boundaries, shared-file semantics, preparation, and receipt ownership.
|
||||
2. Write `docs/roadmap/next-release-notes.md` as the next release's pending notes
|
||||
and migration guidance. A release version is not selected by this feature;
|
||||
2. Write the next release's pending notes and migration guidance.
|
||||
A release version is not selected by this feature;
|
||||
keep the draft under roadmap ownership until release preparation assigns its
|
||||
`docs/releases/<version>.md` destination. Include API/profile updates, the
|
||||
preparation signature and tag field changes, receipt regeneration, CI mapping
|
||||
@@ -764,7 +764,9 @@ implemented examples and canonical documentation agree with the current API.
|
||||
Gitea and internal ownership documents, recovery guidance, and maintained
|
||||
examples for module selection, full tags, path bases, shared files, preparation,
|
||||
and receipt ownership. Added pending next-release notes with migration guidance
|
||||
and corrected the current Go minimum facts. Audited acceptance coverage against
|
||||
and corrected the current Go minimum facts. Release preparation promoted those
|
||||
notes to [the v0.4.0 release note](../releases/v0.4.0.md).
|
||||
Audited acceptance coverage against
|
||||
the stage-owned tests and reviewed ReleaseKit's root release procedure against
|
||||
the adopted release policy; no new release gates were added. Verified
|
||||
`go test ./...`, `go run ./internal/apicheck`, local links and heading fragments
|
||||
|
||||
@@ -1,119 +0,0 @@
|
||||
# Pending notes for the next release
|
||||
|
||||
Status: pending release preparation. This feature does not select a release
|
||||
version or move this draft to `docs/releases/<version>.md`.
|
||||
|
||||
## Release individual Go modules
|
||||
|
||||
ReleaseKit operations can now select one Go module within a Git repository.
|
||||
Omitted module selection retains the repository-root default. A selected module
|
||||
is identified by both its repository-relative physical directory and its own
|
||||
declared module path. ReleaseKit derives a semantic version's complete Git tag
|
||||
from that identity, including Go's `/v2` major-version convention. For example,
|
||||
`v2.1.0` for a module declared as `example.com/project/integrations/core/v2`
|
||||
uses `integrations/core/v2.1.0`, whether the module is physically stored at
|
||||
`integrations/core` or `integrations/core/v2`. Its release note stays at the
|
||||
physical module's `docs/releases/v2.1.0.md` path.
|
||||
|
||||
The public `Check`, `Publish`, `Build`, and `Deliver` requests add `ModuleDir`;
|
||||
results expose the resolved module directory, declared module path, and complete
|
||||
tag alongside existing commit and outcome evidence. `Version` remains the
|
||||
stable semantic version used in note titles, binary version output, and asset
|
||||
names. Git publication and hosted delivery use the complete tag. Product
|
||||
commands receive both repository and module paths, and candidate callbacks
|
||||
receive the module identity.
|
||||
|
||||
`ValidationSpec.SharedFiles` and profile `validation.shared_files` allow a
|
||||
repository-relative list of committed shared files to join optional file
|
||||
checks. Omission or `null` selects the available root `COPYRIGHT`, `LICENSE`,
|
||||
and `docs/oss/attribution.md` defaults; an explicit list replaces those
|
||||
defaults, and `[]` selects none. Explicit files must exist even when file
|
||||
checks are disabled. This selection does not enable a check.
|
||||
|
||||
Profiles add `module_dir` for physical module selection. The CLI's `ci-deliver`
|
||||
now takes a full Git `TAG`; its final path component supplies the semantic
|
||||
version. The optional `--prepared` mode verifies an already prepared checkout
|
||||
without fetching or checking it out again. `--expected-module` binds a mapped
|
||||
launcher selection to the selected profile. The public tagged-checkout request
|
||||
renames `Version` to `Tag` and adds `VerifyOnly`; dependency preparation now
|
||||
takes a `DependencyPreparationRequest` with repository and module directories.
|
||||
`DeliveryRequest.ExpectedTag` binds delivery to the exact CI event tag before
|
||||
building artifacts or contacting Gitea.
|
||||
|
||||
The private `.releasekit-build.json` receipt now requires schema version 1 and
|
||||
binds artifacts to the module directory, declared module path, semantic
|
||||
version, complete tag, source commit, normalized build settings, and artifact
|
||||
declarations. Older and unversioned receipts are rejected; rebuild with the
|
||||
updated `build` command before using `deliver --assets DIR`.
|
||||
|
||||
Relative `build --output DIR` and `deliver --assets DIR` paths both use the
|
||||
selected module directory. Nested-module consumers can use the same relative
|
||||
directory for building and retrying delivery; absolute directories remain usable.
|
||||
|
||||
The maintained [multi-module example](../../examples/multi-module/) shares a
|
||||
four-column `release-modules.tsv` and POSIX selector between its local launcher
|
||||
and mapped Woodpecker workflow. The workflow verifies and detaches the triggering
|
||||
tag before reading the mapping, profile, module files, or ReleaseKit version.
|
||||
Retries therefore use the original tagged source after the default branch
|
||||
changes. Root-only consumers can keep the ordinary profile and the simpler
|
||||
[root tag workflow](../../examples/woodpecker/tag-delivery.yml) without a map.
|
||||
|
||||
## Consumer migration
|
||||
|
||||
Update callers, profiles, receipts, and CI declarations together for this
|
||||
clean interface cutover; compatibility shims and legacy receipt readers are
|
||||
not provided.
|
||||
|
||||
Select this feature's ReleaseKit release in each consumer module before adopting
|
||||
the new profiles and workflows. Upgrade its tool declaration and workflow
|
||||
together: pre-feature tools through v0.3.0 require their historical profiles and
|
||||
flags. Historical tag retries use the workflow matching the tool recorded at
|
||||
that tag. Preserve the immutable
|
||||
tag and module files when retrying.
|
||||
|
||||
- Set `ModuleDir` in Go requests or `module_dir` in profiles for a nested
|
||||
module. The selected directory must contain its own `go.mod`; module paths
|
||||
and release tags are read from that declaration, not inferred from a folder
|
||||
name. Keep `Version` as a semantic version in ordinary commands and API calls.
|
||||
- Update reads of result identity to use `ModuleDir`, `ModulePath`, and `Tag`
|
||||
where needed. Product commands can use `RELEASEKIT_REPOSITORY_DIR` and
|
||||
`RELEASEKIT_MODULE_DIR` to distinguish repository-level work from
|
||||
module-local checks.
|
||||
- Replace `TaggedCheckoutRequest.Version` with the complete `Tag`. Set
|
||||
`VerifyOnly` when a bootstrap step already verified and detached the event
|
||||
checkout. Change `PrepareBuildDependencies` calls to pass a
|
||||
`DependencyPreparationRequest`.
|
||||
- Add `module_dir` and, when needed, `validation.shared_files` to profiles.
|
||||
Recheck profile-relative and repository-relative paths. Prepare and commit
|
||||
each binary module's `go.sum` before tagging so dependency preparation leaves
|
||||
the tagged source clean for delivery verification.
|
||||
- Change `ci-deliver VERSION` invocations to pass the full event `TAG` and
|
||||
required `--commit OID`. Maintained bootstraps should use `--prepared` after
|
||||
verifying the tag and commit. A mapped launcher should pass
|
||||
`--expected-module DIR`; the profile remains the source of selection.
|
||||
- Regenerate existing build receipts with the new `build` command before
|
||||
prebuilt delivery. Do not edit old receipts into the new format.
|
||||
- Root-module validation now excludes independently released nested modules
|
||||
from module-scoped file checks. Run a nested module's checks from that module
|
||||
when it is the release unit. Nested module fixtures remain available to the
|
||||
parent module's product tests.
|
||||
|
||||
ReleaseKit's current consumer minimum remains Go 1.26.0. Root-module releases
|
||||
retain their existing note path, unprefixed tags, profile defaults, and small
|
||||
root-only workflow. A successful push of the intended source tag remains the
|
||||
source-release completion point; hosted page and asset delivery remains
|
||||
asynchronous and may be retried from the same immutable tag. No live-service,
|
||||
deployment, or consumer-rollout gate is introduced.
|
||||
|
||||
For current behavior, see the [API and consumer guides](../consumers/),
|
||||
[CLI contract](../cli.md), [configuration reference](../config.md),
|
||||
[Gitea integration](../integrations/gitea.md), and
|
||||
[ReleaseKit release procedure](../release.md).
|
||||
|
||||
## Release preparation
|
||||
|
||||
Once this release's version is selected, record it in the maintained multi-module
|
||||
example's tool and require directives, and move these notes to its release-note
|
||||
path. Example setup currently selects a compatible version explicitly; disposable
|
||||
fixtures can verify current source before publication. Synthetic dependency
|
||||
versions belong to generated test metadata and local fixture proxies.
|
||||
Reference in New Issue
Block a user