Viewing is open to everyone. Downloading and starring need a GitHub sign-in.
Sign in with GitHub
PUBLISHING.md
v0.1.0-build.85
Latest
Commit ede38f5
Sign in with GitHub to download. Each download is recorded with your GitHub username.
| 1 | # Publishing a release |
| 2 | |
| 3 | A release is published in two steps: |
| 4 | |
| 5 | 1. **Build (automatic).** Pushing a tag `v0.1.0-build.N` on `Stable-Release` runs the Release workflow. It checks the tag against `VERSION`, runs the full test suite, builds every package on Linux, macOS and Windows, signs build provenance with Sigstore, and attaches everything to a **draft** GitHub Release with `SHA256SUMS`. Nothing is published yet. |
| 6 | 2. **Publish (on the maintainer's machine).** `tools/release/publish.sh <tag>` downloads that draft, verifies every checksum and provenance attestation, and publishes the same bytes to each registry. It rebuilds nothing. |
| 7 | |
| 8 | ```sh |
| 9 | tools/release/publish.sh v0.1.0-build.83 # every registry, then un-draft the release |
| 10 | tools/release/publish.sh v0.1.0-build.83 npm nuget # only some |
| 11 | ``` |
| 12 | |
| 13 | Targets: `npm`, `nuget`, `maven`, `homebrew`, `release`. Swift needs no publishing: the tag is the release. |
| 14 | |
| 15 | ## One-time setup |
| 16 | |
| 17 | Tools on the Mac: |
| 18 | |
| 19 | ```sh |
| 20 | brew install gh gnupg node |
| 21 | brew install --cask dotnet-sdk |
| 22 | gh auth login |
| 23 | ``` |
| 24 | |
| 25 | ### npm: package `openckey` |
| 26 | |
| 27 | 1. Create an account at <https://www.npmjs.com/signup> and turn on two-factor authentication. |
| 28 | 2. `npm login` on the Mac. |
| 29 | 3. The package is `openckey`. The unscoped name `ckey` belongs to an unrelated 2018 package, so it cannot be used. |
| 30 | |
| 31 | ### NuGet: packages `CKey` and `CKey.Wpf` |
| 32 | |
| 33 | 1. Sign in at <https://www.nuget.org> with a Microsoft account. |
| 34 | 2. **API Keys → Create**: scope *Push new packages and package versions*, glob `CKey*`. |
| 35 | 3. `export NUGET_API_KEY=…` in the shell before running the script. Do not save it in the repository. |
| 36 | |
| 37 | ### Maven Central: `org.openckey:ckey`, `ckey-compose`, `ckey-camerax` |
| 38 | |
| 39 | 1. Create an account at <https://central.sonatype.com>. |
| 40 | 2. **Namespaces → Add namespace** `org.openckey`. Central shows a verification key; add it as a DNS TXT record on `openckey.org` (Cloudflare → DNS → Add record → TXT, name `@`). Press **Verify** once it resolves. |
| 41 | 3. **Account → Generate User Token.** Then `export MAVEN_CENTRAL_TOKEN=$(printf '%s:%s' '<username>' '<password>' | base64)`. |
| 42 | 4. Create a signing key and publish its public half: |
| 43 | |
| 44 | ```sh |
| 45 | gpg --quick-generate-key "ClearKey Solutions <you@example.com>" ed25519 sign 3y |
| 46 | gpg --list-keys --keyid-format long # note the key ID |
| 47 | gpg --keyserver keyserver.ubuntu.com --send-keys <KEYID> |
| 48 | export GPG_KEY_ID=<KEYID> |
| 49 | ``` |
| 50 | |
| 51 | 5. The script uploads a signed bundle as a *user-managed* deployment. Open <https://central.sonatype.com/publishing/deployments>, check the validation, and press **Publish**. Artifacts appear on Maven Central within about 30 minutes. |
| 52 | |
| 53 | ### Homebrew: `brew install clearkeysolutions/ckey/ckey` |
| 54 | |
| 55 | 1. Create the public repository `clearkeysolutions/homebrew-ckey` on GitHub with an empty `Formula/` folder. |
| 56 | 2. The script copies the release's `ckey.rb` into `Formula/ckey.rb` and pushes it. The formula builds the CLI from the tagged source archive and checks its SHA-256. |
| 57 | |
| 58 | ### Swift |
| 59 | |
| 60 | Nothing to publish. SwiftPM resolves the tag directly: `.package(url: "https://github.com/clearkeysolutions/ckey", from: "0.1.0-build.83")`. Optionally add the package at <https://swiftpackageindex.com/add-a-package> so it can be found. |
| 61 | |
| 62 | ## Cutting a release |
| 63 | |
| 64 | 1. On `scratch`: `python3 tools/bump_version.py`, add the `CHANGELOG.md` entry, and run the full test suite and `python3 tools/check_version.py`. |
| 65 | 2. Promote to `Stable-Release` (`CONTEXT.md` stays on `scratch`) and add the release to `CHANGELOG-STABLE.md`. |
| 66 | 3. Tag the `Stable-Release` commit: `git tag -s v0.1.0-build.N -m "CKey 0.1.0-build.N"` and `git push origin v0.1.0-build.N`. |
| 67 | 4. Wait for the Release workflow's draft, then run `tools/release/publish.sh v0.1.0-build.N`. |
| 68 | 5. Bring `community` level with `Stable-Release`. |
| 69 | |
| 70 | The full procedure, including deprecation, is in the [release and versioning map](RELEASE-AND-VERSIONING-MAP.md). |
| 71 | |
| 72 | ## Security rules |
| 73 | |
| 74 | - Tokens live only in the maintainer's shell (or a password manager), never in the repository and never in a workflow that runs for `community`. |
| 75 | - Published versions are permanent. npm, NuGet and Maven Central do not allow a version to be replaced; a bad release is fixed by the next build number and the old one is deprecated. |