Complete implementation handoff documentation
This commit is contained in:
@@ -1,40 +1,82 @@
|
||||
# Internal package inventory
|
||||
# Package and capability inventory
|
||||
|
||||
Public facades and their contracts are defined in Go declarations and GoDoc.
|
||||
The [runtime consumer guide](../consumers/runtime-version.md) covers application
|
||||
usage, and the [CLI contract](../cli.md) covers command behavior.
|
||||
Public Go contracts are defined in declarations and GoDoc. ReleaseKit supports
|
||||
two Go facades and a command-line interface:
|
||||
|
||||
Implemented internal packages:
|
||||
- The root `releasekit` package is the orchestration facade. `Check` validates
|
||||
one local candidate, `Publish` validates and publishes its exact annotated
|
||||
source tag, `Build` compiles selected application targets, and `Deliver`
|
||||
delivers a tagged note page and any declared assets.
|
||||
- `buildinfo` is the small runtime facade. `Version` reports the injected
|
||||
application version, the main-module version when available, or `dev`.
|
||||
- `cmd/releasekit` is the executable interface. Its `version`, `check`,
|
||||
`publish`, `build`, and `deliver` commands adapt profiles and command output
|
||||
to the supported library operations.
|
||||
|
||||
- `internal/runtimeinfo` holds the injected version value and selects the
|
||||
executable's main-module version when no injected value is present.
|
||||
- `internal/versioncontract` names the linker symbol and stable version form
|
||||
shared with the build and candidate operations.
|
||||
- `internal/apicheck` checks compiled exports with `go/types` and checks import
|
||||
direction. Run it with `go run ./internal/apicheck` from the repository root.
|
||||
- `internal/process` runs cancellable child commands with per-child environment
|
||||
overlays.
|
||||
- `internal/build` compiles explicit Go targets with shared version injection,
|
||||
verifies native version output, and returns generated file digests.
|
||||
- `internal/gitea` verifies hosted source tags, manages matching stable release
|
||||
pages, and inspects and uploads declared attachments through the Gitea REST API.
|
||||
- `internal/candidate` captures and validates one clean local candidate, checks
|
||||
its committed release note and local tag state, runs validation once, and
|
||||
rechecks mutable repository state.
|
||||
- `internal/git` resolves one effective push destination, applies it to a
|
||||
command-scoped remote, reads exact authoritative branch and tag refs, and
|
||||
creates and pushes exact annotated tag objects.
|
||||
- `internal/publish` coordinates local and remote guards around one validation
|
||||
run and reports the publication state reached by that invocation.
|
||||
- `internal/delivery` verifies a tagged checkout and coordinates note, build
|
||||
identity, hosted page, asset inspection, and additive upload outcomes.
|
||||
- `cmd/releasekit/internal/cli` parses implemented commands, loads strict JSON
|
||||
profiles, adapts configured checks, and writes and validates private local
|
||||
build receipts used for delivery.
|
||||
See the [CLI contract](../cli.md), [configuration reference](../config.md),
|
||||
[candidate check guide](../consumers/check.md),
|
||||
[build guide](../consumers/build.md),
|
||||
[delivery guide](../consumers/delivery.md), and
|
||||
[runtime version guide](../consumers/runtime-version.md) for task-oriented use.
|
||||
Go declarations and GoDoc remain the owners of exact exported contracts.
|
||||
|
||||
The executable controller uses the runtime facade and the command-owned CLI
|
||||
adapter. The adapter uses the process runner and imports neither public facade.
|
||||
The publication operation coordinates the candidate and Git packages. The
|
||||
internal Gitea client is documented in the
|
||||
[Gitea integration guide](../integrations/gitea.md); tagged-source orchestration
|
||||
is exposed through the public delivery facade and CLI.
|
||||
## Module and dependencies
|
||||
|
||||
The module is `gitea.maximumdirect.net/eric/ReleaseKit`, with Go language
|
||||
version `1.25.0`. `go.mod` has no required third-party modules; packages use the
|
||||
standard library and first-party ReleaseKit packages. `go list ./...` reports
|
||||
these implemented packages:
|
||||
|
||||
| Package | Responsibility |
|
||||
| --- | --- |
|
||||
| `releasekit` | Public orchestration facade and consumer-owned request/result types. |
|
||||
| `buildinfo` | Public runtime version accessor. |
|
||||
| `cmd/releasekit` | Executable entry point, command routing, output, and exit status. |
|
||||
| `cmd/releasekit/internal/cli` | Command parsing, strict JSON profile loading, configured checks, and private build receipts. |
|
||||
| `internal/apicheck` | Compiled-export and import-boundary checks run during development. |
|
||||
| `internal/build` | Selected Go target compilation, version injection, native smoke check, and artifact digests. |
|
||||
| `internal/candidate` | Stable-version, note, repository-state, candidate capture, and post-validation checks. |
|
||||
| `internal/delivery` | Tagged-checkout verification and coordination of release pages, assets, and delivery results. |
|
||||
| `internal/git` | Git command boundary, push-destination resolution, exact ref inspection, and tag operations. |
|
||||
| `internal/gitea` | Gitea API transport, hosted release pages, asset inspection, manifests, and uploads. |
|
||||
| `internal/process` | Cancellable child-process execution with per-command environment overlays. |
|
||||
| `internal/publish` | Publication guards, one validation run, annotated tag creation, push, and recovery state. |
|
||||
| `internal/runtimeinfo` | Private version lookup used by the runtime facade. |
|
||||
| `internal/versioncontract` | Shared stable-version rules and linker-symbol identity. |
|
||||
|
||||
The `buildinfo` facade depends only on its small runtime implementation. The
|
||||
root facade forwards to internal implementation packages. The CLI adapter is
|
||||
owned under `cmd/releasekit/internal`; implementation packages do not import
|
||||
either public facade. `internal/apicheck` verifies exported type ownership and
|
||||
dependency direction with `go run ./internal/apicheck`. These constraints are
|
||||
also recorded in [ADR 0001](../adr/0001-public-facade.md) and the
|
||||
[architecture policy](../policy/architecture.md).
|
||||
|
||||
## Capability owners and behavioral evidence
|
||||
|
||||
The following tests are representative evidence from the current offline suite,
|
||||
not a separate release matrix:
|
||||
|
||||
| Capability | Implementation owner | Existing evidence |
|
||||
| --- | --- | --- |
|
||||
| Runtime version lookup and injected application version | `buildinfo`, `internal/runtimeinfo`, `internal/versioncontract`, `internal/build` | `TestVersionInConsumerExecutable`, `TestVersion` |
|
||||
| Candidate capture, committed note, one validation, and rechecks | `releasekit.Check`, `internal/candidate`, `cmd/releasekit/internal/cli` | `TestCheckCapturesCandidateAndCallsValidationOnce`, `TestCheckRechecksHeadAndWorktreeAfterCallback`, `TestCheckCommandBindsConfiguredChecksToCapturedCandidate` |
|
||||
| Authoritative endpoint and exact annotated tag publication | `releasekit.Publish`, `internal/publish`, `internal/git` | `TestPublishPushesOnlyTheCapturedAnnotatedTag`, `TestResolveUsesPushURLAndQueriesWithoutMutation` |
|
||||
| Publication partial and uncertain recovery | `internal/publish` | `TestPublishRejectedPushKeepsLocalTagAndReportsNotPublished`, `TestPublishLostAcknowledgmentConfirmsExactRemoteObject`, `TestPublishUnavailableReconciliationRemainsUnknownAndPreservesPushError` |
|
||||
| Cross-builds, version smoke checks, empty target sets, and partial outputs | `releasekit.Build`, `internal/build`, `buildinfo` | `TestBuildCreatesSelectedTargetsAndInjectsVersion`, `TestBuildWithNoTargetsDoesNotInvokeCompiler`, `TestBuildReturnsPartialArtifactsAfterTargetFailure` |
|
||||
| Page-only and binary tagged-source delivery | `releasekit.Deliver`, `internal/delivery`, `internal/gitea`, CLI | `TestDeliverPageOnlyCreatesAndReusesRelease`, `TestDeliverBuildsTaggedArtifactsAndReusesAssets`, `TestDeliverRejectsTamperedAssetsAndStaleReceiptBeforeRemoteWrites` |
|
||||
| Page, manifest, asset comparison, and additive retry outcomes | `internal/gitea` | `TestEnsureReleaseCreatesMissingPageFromCommittedNote`, `TestInspectAssetsDetectsSameNameAndSizeWithDifferentBytes`, `TestUploadMissingPartialFailureThenRerunOnlyMissingAssets` |
|
||||
| CLI profiles and prepared Woodpecker sequences | `cmd/releasekit`, `cmd/releasekit/internal/cli`, `examples/woodpecker/` | `TestLoadSettingsRejectsInvalidProfiles`, `TestWoodpeckerDeliveryCommandSequences`, `TestReleaseKitSourceDeliveryWorkflowFromTaggedCheckout` |
|
||||
|
||||
Run the complete suite with `go test ./...`. The public API and import boundary
|
||||
check is `go run ./internal/apicheck`. Local HTTP and Git fixtures exercise
|
||||
publication and delivery without real credentials or a hosted service.
|
||||
|
||||
## Integration references
|
||||
|
||||
The [Gitea integration guide](../integrations/gitea.md) owns the HTTP contract
|
||||
and hosted response handling. The [Woodpecker examples](../../examples/woodpecker/)
|
||||
are prepared integrations; their YAML is not active in this repository, and no
|
||||
live Woodpecker runner, configured secret, or hosted delivery has been used.
|
||||
Consumer migrations and measurement of removed consumer infrastructure remain
|
||||
future adoption work.
|
||||
|
||||
Reference in New Issue
Block a user