Skip to content

docs(distribution): describe multi-binary identity manifests #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rianjs merged 1 commit into from
Sep 3, 2026
Merged

docs(distribution): describe multi-binary identity manifests #74

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions docs/distribution.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -424,6 +424,53 @@ The nfpm `package_name` and the dispatch `package` key MUST match the manifest's
`packages.linux.package_name` — a mismatch routes packages under the wrong name
in `linux-packages`.

### §8.4 Several binaries from one release

A repo that ships more than one binary from **one module, one goreleaser config and
one tag stream** (`google-cli` ships `gro` and `grw` as `v1.2.N`) declares them in
a single manifest with `binaries:` instead of `binary:`. `repo`, `goreleaser_config`,
`version_file` and `tag` stay top-level; everything that is per-binary
(`archives`, `packages`, `keychain_probe`) moves under each entry:

@monit-reviewer monit-reviewer Sep 3, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Low (documentation:docs-reviewer): The example tag scheme value version_scheme: major_minor_run_patch reads oddly ("run" between minor and patch). If this isn't an actual accepted value in the identity manifest schema, it's a typo that readers may copy verbatim into their own packaging/identity.yml. Worth double-checking against the schema/identity-check validator before merge.

Reply to this thread when addressed.

@rianjs rianjs Sep 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is a real value: identity-check exports tag.version_scheme verbatim and §8.1 documents major_minor_run_patch (version.txt = MAJOR.MINOR, patch = workflow run number).

```yaml
schema: open-cli-identity/v1
repo: google-cli
goreleaser_config: .goreleaser.yaml
version_file: version.txt
tag: { prefix: v, version_scheme: major_minor_run_patch }
binaries:
- name: gro
archives: { name_template: "gro_v{{ .Version }}_{{ .Os }}_{{ .Arch }}" }
packages:
homebrew: { canonical_cask: gro, alias_casks: [google-readonly] }
winget: { id: OpenCLICollective.google-readonly }
chocolatey: { id: google-readonly }
linux: { package_name: google-readonly }
keychain_probe: { ... }
- name: grw
archives: { name_template: "grw_v{{ .Version }}_{{ .Os }}_{{ .Arch }}" }
packages: { ... }
```

A manifest declares exactly one of `binary:` or `binaries:`; `identity-check`
normalizes both to a `binaries` list for the workflows. The per-binary rules:

- Every goreleaser build sets `id:` and `binary:`. Each `archives[]`, `nfpms[]`
and `homebrew_casks[]` entry must select **one** binary's builds/archives via
`ids:`; an unfiltered entry (fine for a single binary) is a drift error here.
Templates, package names and cask names are checked against the owning binary.
- Chocolatey packages nest per id: `packaging/chocolatey/<id>/<id>.nuspec` and
`packaging/chocolatey/<id>/tools/`. winget manifests stay in `packaging/winget/`
(they are id-named already).
- `release.yml` builds once, then runs each channel (homebrew, chocolatey, winget,
linux-packages) as a matrix over the binaries that declare it, resolving each
binary's Windows archives from `dist/artifacts.json`; the darwin gate and the
code-signing identifier (`org.open-cli-collective.<name>`) run per binary.

This is distinct from §8.3: a monorepo of independently versioned tools keeps one
manifest per tool and prefixed tags; `binaries:` is for binaries that always ship
together under one version.

---

## §9 Consuming the reusable workflow
Expand Down
Loading