159 lines
7.9 KiB
Markdown
159 lines
7.9 KiB
Markdown
# 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.
|