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

Plan implementation of individual module releases

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-10 01:34:33 +00:00
parent f33023f8e0
commit dbfae9ea81
3 changed files with 861 additions and 200 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
docs/roadmap/commandkit-feature-request.md Normal file
View File

@@ -0,0 +1,158 @@
# CommandKit feature request: publish individual modules in a shared repository
Status: requested upstream capability; not an implemented ReleaseKit contract.
## Consumer context
CommandKit uses ReleaseKit v0.3.0 for source-only publication. CommandKit is
still an unreleased prototype and is preparing to separate its core from
optional integrations into three independently versioned Go modules:
| Repository directory | Module path | Illustrative version | Corresponding Git tag |
| --- | --- | --- | --- |
| Root | `gitea.maximumdirect.net/eric/CommandKit` | `v0.1.0` | `v0.1.0` |
| `integrations/ckconfig` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `v0.2.0` | `integrations/ckconfig/v0.2.0` |
| `integrations/ckprompt` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `v0.1.0` | `integrations/ckprompt/v0.1.0` |
These versions illustrate independent numbering; they are not selected initial
release versions. Integration versions will describe their own changes rather
than matching either CommandKit core or upstream library versions.
The dependency direction is `ckprompt` toward `ckconfig` and core, and
`ckconfig` toward core. Consumers should acquire only their selected integrations
and their dependencies. Each integration therefore needs its own module files,
validation, release notes, and publication identity. More integration modules may
follow without requiring a new publication mechanism for each one.
Go requires repository-subdirectory prefixes on nested module version tags.
The semantic module version remains `vMAJOR.MINOR.PATCH`; the complete Git tag
additionally identifies the module directory. See the
[Go module reference](https://go.dev/ref/mod#vcs-version).
## Issue with the current publication contract
ReleaseKit's documented [CLI](../cli.md), [profile](../config.md), and
[publication API](../consumers/publish.md) assume one release version/tag and
one standard Go suite. Release notes use repository-root
`docs/releases/<version>.md`, and publication accepts stable
`vMAJOR.MINOR.PATCH` rather than a nested module's prefixed tag.
Changing the product name or choosing another profile does not provide a
separate module directory, semantic version, and Git tag identity. Running the
root module's suite also does not validate packages belonging to nested modules.
CommandKit would otherwise need to implement its own integration publication
path, duplicating functionality already owned by ReleaseKit. We would prefer
ReleaseKit to support selecting one Go module within the shared repository.
## Requested feature
Support checking and publishing one explicitly selected module per invocation,
through the public library API and native CLI/profile interface. The request is
about observable behavior; ReleaseKit should select its own internal design.
### Repository and module selection
- Distinguish the Git repository from the selected module's directory within it.
- Keep repository state, candidate commit, branch, remote, and publication guards
scoped to the shared repository.
- Execute the standard Go validation suite in the selected module. Its tests,
and any selected module-specific vet or package compilation, should operate on
that module rather than implicitly validating only the repository-root module.
- Preserve ordinary root-module publication when no nested module is selected.
- Permit a shared repository launcher to choose small per-module profiles without
requiring separate Git repositories or duplicated publication logic.
### Version and tag identity
- Accept the selected module's semantic version separately from its repository
subdirectory, deriving the corresponding Go module tag from those inputs.
- Use the complete tag for uniqueness checks, tag creation, publication, and
failed or ambiguous publication recovery.
- Make both module version and complete tag identifiable in public results and
CLI output, alongside the candidate commit and existing publication evidence.
- Allow modules to publish different versions and to release individually.
Equal semantic versions in different modules identify different tags.
No arbitrary tag-template language is needed by CommandKit. Standard Go module
tag conventions meet its requirements.
### Release notes
Support a distinct committed note for each module release, even when two modules
use the same semantic version. CommandKit's preferred layout is module-local
`docs/releases/<version>.md`, for example:
```text
docs/releases/v0.1.0.md
integrations/ckconfig/docs/releases/v0.2.0.md
integrations/ckprompt/docs/releases/v0.1.0.md
```
Validate the selected note against its product and semantic version in the
captured candidate. The complete tag remains the immutable source identity for
note links, licensing links, and publication recovery. A documented explicit
note-path setting would also be acceptable if module-local discovery is not the
selected public design.
Document how module version, complete tag, note title, and note location relate;
align affected release-policy language with the selected conventions rather than
treating the current single-module note path as an obstacle.
### Validation and completion
Run the selected module's standard suite once for the publication candidate,
retaining ReleaseKit's offline validation and existing publication outcome model.
Additional product checks may cover CommandKit-specific composition or dependency
boundaries without repeating the selected standard suite.
CommandKit will prepare dependencies before offline validation. Its published
modules will require actual released dependency versions; local workspace
composition is useful during development but does not establish ordinary consumer
resolution. For releases requiring new sibling versions, CommandKit can publish
core, then `ckconfig`, then `ckprompt`, preparing each candidate as needed.
Successful source-tag publication should remain the completion point. This
request does not add CI polling, hosted release pages, artifact delivery, module
proxy availability, or consumer installation as publication completion gates.
## Illustrative consumer interface
Conceptually, a request would supply:
```text
Repository: /work/CommandKit
Module directory: integrations/ckconfig
Product: CommandKit ConfigKit integration
Module version: v0.2.0
```
ReleaseKit would select that module's suite and committed note, and publish
`integrations/ckconfig/v0.2.0` for the captured repository candidate. Exact Go
field names, CLI options, and profile syntax remain ReleaseKit design choices.
CommandKit could then expose a small convenience launcher such as
`./scripts/release ckconfig v0.2.0`; that is illustrative consumer syntax, not a
request for ReleaseKit to hard-code CommandKit's module names.
## Acceptance scenarios
1. Publish the root module using ordinary unprefixed tags and existing defaults.
2. Publish either nested integration with its Go-required prefixed tag and its
own committed note, without publishing unrelated module tags.
3. Identify validation failures from the selected nested module and prevent its
publication, even if the root suite would pass.
4. Publish two modules using the same semantic version without note or tag
collisions; preserve existing guards against reusing a published full tag.
5. Report the complete selected tag in known-failure or unresolved-publication
results so recovery addresses the exact destination and tag object.
## Follow-up possibilities
Publishing an explicit set of independently versioned modules in one operation
could later reduce repeated repository checks and support coordinated releases.
Batch or atomic multi-tag publication is not needed for this initial request.
Neither are automatic module discovery, dependency-driven version selection,
matching version numbers, or a generic release-orchestration framework.
CommandKit can adopt single-module selection first and revisit release sets when
concrete maintenance needs justify them.