-
Notifications
You must be signed in to change notification settings - Fork 0
docs(release): Make+Nix release flow with gh publish #16
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.
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
Merged
Changes from all commits
Commits
Show all changes
4 commits
Select commit
Hold shift + click to select a range
1505d4e
docs(release): Make+Nix release flow with gh publish
rtacconi f4d51d8
fix(release): address CodeRabbit PR16 (markdownlint, gh via nix devel…
rtacconi be9ff79
fix(ci): quote kani-shard job name for valid YAML
rtacconi b5d4328
fix(ci): raise kani-shard timeouts (job was capped below install+proof)
rtacconi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,14 @@ | ||
| # kcore X.Y.Z | ||
|
|
||
| ## Highlights | ||
|
|
||
| - | ||
|
|
||
| ## Upgrade / install | ||
|
|
||
| - **ISO**: flash `kcoreos-X.Y.Z-x86_64-linux.iso` (verify `SHA256SUMS`). | ||
| - **kctl**: extract `kcore-kctl-X.Y.Z-linux-x86_64.tar.gz` and run `./kcore-kctl --help` (glibc Linux x86_64, built via this repo’s Nix flake). | ||
|
|
||
| ## Checksums | ||
|
|
||
| See `SHA256SUMS` attached to the GitHub Release. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| # Release process (Make + Nix + GitHub Releases) | ||
|
|
||
| Releases are **operator-driven**: build artifacts locally with Nix, publish to GitHub with `gh`. There is no release workflow in GitHub Actions; CI on `main` remains the quality gate only. | ||
|
|
||
| ## Version sources (policy) | ||
|
|
||
| | Source | Role | | ||
| |--------|------| | ||
| | [`VERSION`](../VERSION) (single line, e.g. `0.2.0`) | **Product / packaging version**: Nix `kcoreVersion`, ISO filename `kcoreos-$(VERSION)-x86_64-linux.iso`, Git tag `v$(VERSION)`, release assets. **Bump this for every release.** | | ||
| | `crates/*/Cargo.toml` `version = "…"` | Rust crate semver (currently `0.1.0` for workspace members). **Not automatically tied to `VERSION`.** Optional: bump crate versions in the same PR as `VERSION` if you want `kcore-kctl --version` to match the product version everywhere. | | ||
|
|
||
| ## Preconditions | ||
|
|
||
| - **Host**: Linux **x86_64** with Nix and flakes working (`nix build .#kcore-kctl`). | ||
| - **GitHub CLI**: `gh` installed and authenticated (`gh auth login`) with `contents: write` on the repo. Optional: set `GH_REPO=owner/repo` if not using the default remote. | ||
| - **Tag**: The annotated tag `v$(cat VERSION)` must exist **on the remote** before `make release-publish` (the script uses `gh release create --verify-tag`). | ||
|
|
||
| ## Steps | ||
|
|
||
| 1. **Bump version** | ||
| Edit [`VERSION`](../VERSION) to `X.Y.Z` (and optionally align `crates/kctl/Cargo.toml` and other crates if you follow the policy above). Open a PR, get CI green, merge to `main`. | ||
|
|
||
| 2. **Tag the release commit** (on `main` after merge): | ||
|
|
||
| ```bash | ||
| git fetch origin main && git checkout main && git pull | ||
| git tag -a "v$(tr -d '\n' < VERSION)" -m "kcore $(tr -d '\n' < VERSION)" | ||
| git push origin "v$(tr -d '\n' < VERSION)" | ||
| ``` | ||
|
|
||
| 3. **Quality gate (recommended)** | ||
| `make check` and/or `make test-all` per [rust-quality-checks](../.cursor/rules/rust-quality-checks.mdc). | ||
|
|
||
| 4. **Build artifacts (Nix)** | ||
| At the same commit as the tag (or clean tree on `main` at that commit): | ||
|
|
||
| ```bash | ||
| make release-build | ||
| ``` | ||
|
|
||
| This runs [`scripts/release.sh`](../scripts/release.sh) `build`: ISO → `result-iso/`, `kcore-kctl` → `result-kctl/`. | ||
|
|
||
| 5. **Package `dist/`** | ||
| Produces the GitHub upload set: | ||
|
|
||
| ```bash | ||
| make release-dist | ||
| ``` | ||
|
|
||
| - `dist/kcore-kctl-$(VERSION)-linux-x86_64.tar.gz` (binary at archive root: `kcore-kctl`) | ||
| - `dist/kcoreos-$(VERSION)-x86_64-linux.iso` (release asset name; copied from the single ISO produced under `result-iso/iso/`) | ||
| - `dist/SHA256SUMS` for both files | ||
|
|
||
| Or in one step after a successful build: `make release` (build + dist; does not publish). | ||
|
|
||
| 6. **Release notes** | ||
| Copy the template and edit: | ||
|
|
||
| ```bash | ||
| cp RELEASE_NOTES.template.md RELEASE_NOTES.md | ||
| # edit RELEASE_NOTES.md (not committed; see .gitignore) | ||
| ``` | ||
|
|
||
| Publish uses `RELEASE_NOTES` env if you need another path: `RELEASE_NOTES=path/to/notes.md make release-publish`. | ||
|
|
||
| 7. **Publish the GitHub Release** | ||
|
|
||
| ```bash | ||
| make release-publish | ||
| ``` | ||
|
|
||
| This runs `nix develop --command gh release create v$(VERSION) --verify-tag` (GitHub CLI from the dev shell) and uploads the tarball, ISO, and `SHA256SUMS`. | ||
|
|
||
| ## Artifact notes | ||
|
|
||
| - **kctl** in the tarball is the **Nix-built** `kcore-kctl` from `.#kcore-kctl` (same lineage as the ISO), not a raw `cargo build`. | ||
| - **Platform**: **linux x86_64** (glibc via Nix). No musl/static build in this flow. | ||
| - **Large files**: ISOs are ~1–2 GiB; GitHub per-file limit is 2 GiB. Stay under that or split hosting for huge artifacts. | ||
|
|
||
| ## Troubleshooting | ||
|
|
||
| - **`gh release create` fails on `--verify-tag`**: push the tag first: `git push origin vX.Y.Z`. | ||
| - **Wrong ISO name**: Nix may place the built ISO under a NixOS-derived name in `result-iso/iso/`; the dist step discovers the single `*.iso` there and copies it to the release asset name `kcoreos-$(VERSION)-x86_64-linux.iso`. | ||
| - **Token in automation**: set `GH_TOKEN` in the environment for non-interactive `gh` (e.g. CI in the future); this doc targets local operator use. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| #!/usr/bin/env bash | ||
| # Build release artifacts (Nix ISO + kcore-kctl), package dist/, publish GitHub Release. | ||
| # Usage: | ||
| # ./scripts/release.sh build # nix build ISO + kcore-kctl -> result-iso, result-kctl | ||
| # ./scripts/release.sh dist # dist/*.tar.gz, ISO copy, dist/SHA256SUMS | ||
| # ./scripts/release.sh publish # gh release create (needs tag on remote, RELEASE_NOTES.md) | ||
| # Environment: | ||
| # RELEASE_NOTES Path to release notes file (default: RELEASE_NOTES.md) | ||
| # GH_REPO owner/repo override for gh (optional; defaults to git remote) | ||
| set -euo pipefail | ||
|
|
||
| ROOT="$(cd "$(dirname "${0}")/.." && pwd)" | ||
| cd "${ROOT}" | ||
|
|
||
| VERSION="$(tr -d '\n' < VERSION)" | ||
| ISO_NAME="kcoreos-${VERSION}-x86_64-linux.iso" | ||
| KCTL_ARCHIVE="kcore-kctl-${VERSION}-linux-x86_64.tar.gz" | ||
|
|
||
| die() { | ||
| echo "release.sh: $*" >&2 | ||
| exit 1 | ||
| } | ||
|
|
||
| require_cmd() { | ||
| command -v "${1}" >/dev/null 2>&1 || die "missing required command: ${1}" | ||
| } | ||
|
|
||
| cmd_build() { | ||
| require_cmd nix | ||
| echo "==> Building ISO (${ISO_NAME})..." | ||
| nix build ".#nixosConfigurations.kcore-iso.config.system.build.isoImage" -o result-iso | ||
| echo "==> Building kcore-kctl..." | ||
| nix build ".#kcore-kctl" -o result-kctl | ||
| echo "==> Build outputs:" | ||
| ls -lh result-iso/iso/*.iso | ||
| ls -lh result-kctl/bin/kcore-kctl | ||
| } | ||
|
|
||
| cmd_dist() { | ||
| require_cmd tar | ||
| require_cmd sha256sum | ||
| [[ -f result-kctl/bin/kcore-kctl ]] || die "run '${0} build' first (missing result-kctl/bin/kcore-kctl)" | ||
| shopt -s nullglob | ||
| iso_candidates=(result-iso/iso/*.iso) | ||
| shopt -u nullglob | ||
| [[ "${#iso_candidates[@]}" -eq 1 ]] || die "expected exactly one ISO under result-iso/iso/; run '${0} build' first" | ||
| ISO_SRC="${iso_candidates[0]}" | ||
|
|
||
| mkdir -p dist | ||
| echo "==> Packaging ${KCTL_ARCHIVE}..." | ||
| tar -C result-kctl/bin -czf "dist/${KCTL_ARCHIVE}" kcore-kctl | ||
| echo "==> Copying $(basename "${ISO_SRC}") to dist/${ISO_NAME}..." | ||
| cp -f "${ISO_SRC}" "dist/${ISO_NAME}" | ||
| echo "==> Writing dist/SHA256SUMS..." | ||
| ( | ||
| cd dist | ||
| sha256sum "${ISO_NAME}" "${KCTL_ARCHIVE}" >SHA256SUMS | ||
| ) | ||
| echo "==> dist layout:" | ||
| ls -lh dist/ | ||
| cat dist/SHA256SUMS | ||
| } | ||
|
|
||
| cmd_publish() { | ||
| require_cmd nix | ||
| NOTES="${RELEASE_NOTES:-RELEASE_NOTES.md}" | ||
| [[ -f "${NOTES}" ]] || die "missing ${NOTES} - copy RELEASE_NOTES.template.md to RELEASE_NOTES.md and edit" | ||
| [[ -f "dist/${KCTL_ARCHIVE}" ]] || die "run '${0} dist' first" | ||
| [[ -f "dist/${ISO_NAME}" ]] || die "run '${0} dist' first" | ||
| [[ -f dist/SHA256SUMS ]] || die "run '${0} dist' first" | ||
|
|
||
| TAG="v${VERSION}" | ||
| echo "==> Creating GitHub release ${TAG} (verify-tag)..." | ||
| nix develop --command gh release create "${TAG}" \ | ||
| --verify-tag \ | ||
| --title "kcore ${VERSION}" \ | ||
| --notes-file "${NOTES}" \ | ||
| "dist/${KCTL_ARCHIVE}" \ | ||
| "dist/${ISO_NAME}" \ | ||
| dist/SHA256SUMS | ||
| echo "==> Done: nix develop --command gh release view ${TAG}" | ||
| } | ||
|
|
||
| usage() { | ||
| echo "Usage: ${0} {build|dist|publish}" | ||
| exit 1 | ||
| } | ||
|
|
||
| case "${1:-}" in | ||
| build) cmd_build ;; | ||
| dist) cmd_dist ;; | ||
| publish) cmd_publish ;; | ||
| *) usage ;; | ||
| esac |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.