121 lines
6.8 KiB
Markdown
121 lines
6.8 KiB
Markdown
# Source tag publication
|
|
|
|
Use `releasekit.Publish` to validate a committed candidate and push its exact
|
|
annotated source tag:
|
|
|
|
```go
|
|
result, err := releasekit.Publish(ctx, releasekit.ReleaseRequest{
|
|
RepositoryDir: "/work/project",
|
|
ModuleDir: "integrations/example",
|
|
Product: "Example",
|
|
Version: "v1.2.3",
|
|
ExpectedPushURL: "ssh://git.example/owner/example.git",
|
|
Validation: releasekit.ValidationSpec{
|
|
Go: releasekit.GoValidationSpec{Race: true, FullVet: true},
|
|
},
|
|
AdditionalChecks: func(ctx context.Context, candidate releasekit.Candidate) error {
|
|
return runProjectChecks(ctx, candidate.RepositoryDir)
|
|
},
|
|
})
|
|
if err != nil {
|
|
return err
|
|
}
|
|
fmt.Println(result.ModulePath, result.Version, result.Tag, result.CandidateCommit, result.TagObject)
|
|
```
|
|
|
|
`ModuleDir` is a repository-relative physical module directory; omit it or use
|
|
`.` for a root-module release. ReleaseKit reads the selected module's committed
|
|
declaration and derives the complete Git tag from its declared module path and
|
|
physical location. `Version` remains the stable semantic version. The note is
|
|
`<module>/docs/releases/<version>.md`; an on-disk `/v2` directory is part of
|
|
the note path but is removed from the tag prefix only when the module path ends
|
|
in `/v2`. `PublicationResult` returns the absolute `ModuleDir`, declared
|
|
`ModulePath`, complete `Tag`, and existing commit and tag-object evidence.
|
|
|
|
The optional `ValidationSpec.SharedFiles` selects additional committed files
|
|
for enabled file checks. Its nil and empty-slice behavior is described in the
|
|
[candidate check guide](check.md#local-candidate-check).
|
|
|
|
Publication captures a clean candidate on `main`, validates its committed
|
|
release note, and checks the selected remote before running candidate checks.
|
|
Set `ExpectedPushURL` to require the effective push destination to match an
|
|
exact string. Git URL rewrites are resolved first, and the push URL is compared
|
|
when fetch and push URLs differ. A mismatch fails preflight before Go validation,
|
|
callbacks, or tag creation; detect it with
|
|
`errors.Is(err, releasekit.ErrUnexpectedPushURL)`. `Check` ignores this
|
|
publication-only field.
|
|
It runs one `go test -mod=readonly -count=1 ./...` suite with the available
|
|
compatible local Go toolchain. Set `Validation.Go.Race` to run that suite with
|
|
`-race`. Set `Validation.Go.FullVet` to run `go vet -mod=readonly ./...` after
|
|
successful tests, with test-time vet disabled for that suite. The zero values
|
|
keep ordinary test-time vet behavior. It then calls `AdditionalChecks` once
|
|
when supplied. The standard suite cannot be replaced;
|
|
move product-specific behavior into `AdditionalChecks` and remove repeated
|
|
standard-suite commands from custom checks. A failed suite or additional check
|
|
prevents tag creation, and wrapped errors preserve their causes.
|
|
If race prerequisites are unavailable, the selected suite fails as `go-test`
|
|
instead of silently running without the race detector. Full-vet failures are
|
|
reported as `go-vet` and stop publication before tag creation.
|
|
|
|
Set `Validation.Go.CompileTargets` to compile packages for each complete target
|
|
pair after tests and vet. This uses `CGO_ENABLED=0`, produces no artifact, and
|
|
does not execute target binaries. A failure is reported as `package-compile`
|
|
with the selected target and prevents tag creation.
|
|
|
|
Set `Validation.GoFormat` to check committed regular Go source using the Go
|
|
formatter built into ReleaseKit. It includes vendor and nested modules, ignores
|
|
worktree changes and symlink blobs, and reports unformatted paths as
|
|
`go-format` without changing files. The default is disabled. The check follows
|
|
tests, selected vet, and package compilation, and a failure stops publication
|
|
before product checks or tag creation.
|
|
|
|
Set `Validation.ModuleDistribution.WorkspaceFiles` to reject committed
|
|
`go.work` and `go.work.sum` blobs, including nested paths and symlink entries.
|
|
The rule reads the captured candidate regardless of `GOWORK`; uncommitted files
|
|
are ignored, and Go workspace selection and vendor behavior are unchanged. Its
|
|
zero value disables the check. Findings use `workspace-files` and stop
|
|
publication before product checks or tag creation.
|
|
Set `Validation.ModuleDistribution.LocalReplacements` independently to parse
|
|
selected module's committed `go.mod` declarations. Vendored contents remain in
|
|
scope, while independently released nested modules are excluded. Filesystem
|
|
`replace` directives are reported with their source path, line, and target as
|
|
`local-replacements`; versioned replacements are
|
|
permitted. Committed module symlinks are resolved within the candidate, and
|
|
parse or inspection errors retain their causes. This check is independent of
|
|
`GOWORK`; its zero value disables it, and a failure stops publication before
|
|
product checks or tag creation.
|
|
Set `Validation.FileSize` to check each committed blob against a byte limit.
|
|
Nil disables the check; an empty object enables the default of 1,000,000
|
|
decimal bytes. `LimitBytes` uses strict greater-than, accepts zero, and rejects
|
|
negative values. `Exclusions` contains literal files or directories relative to
|
|
the selected module, including committed descendants of excluded directories.
|
|
Symlink blob size is its link text; gitlinks are omitted. This check measures only the
|
|
captured candidate and reports one oversized file with its measurement as
|
|
`file-size`; it stops publication before product checks or tag creation.
|
|
|
|
Set `Validation.Markdown` to check committed local Markdown destinations and
|
|
supported heading fragments during publication. Nil disables the check; an
|
|
empty object enables it with outside-checkout links reported as out of scope.
|
|
Set `EnforceCheckoutBoundary` to fail those links. Submodule contents remain
|
|
out of scope under either setting. Observations use the request's output writer;
|
|
failures use `markdown-links` and stop publication before product checks or tag
|
|
creation.
|
|
|
|
ReleaseKit-owned selections replace duplicate generic suite, vet, formatting,
|
|
distribution, and Markdown checks in configured product checks. Keep
|
|
release-note rules and consumer-specific assertions, such as maintained-example
|
|
tests, in `AdditionalChecks` or profile `checks`.
|
|
|
|
If `Build` selects targets, ReleaseKit verifies them after the standard suite
|
|
and additional checks, before creating the tag. The operation then rechecks the
|
|
candidate and remote guards, creates an annotated tag for the captured commit,
|
|
and pushes only that tag object.
|
|
|
|
A successful result means Git confirmed the push or an exact authoritative tag
|
|
query confirmed it after a push error. The local tag is retained after a failed
|
|
push. `PublicationState` distinguishes a known failure, conflict, confirmed
|
|
publication, and unresolved outcome. Resolve an unknown result against the
|
|
captured endpoint before retrying; see the [maintainer procedure](../release.md)
|
|
for the recovery steps. The [CLI contract](../cli.md) documents command output
|
|
and exit statuses.
|