diff --git a/AGENTS.md b/AGENTS.md index 158e4f3..64c69bb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -454,12 +454,12 @@ and this file is for what someone changing worklane's own code needs. ### Version Bumps - Before every commit, decide whether the change warrants a version bump in `Cargo.toml` - Always ask the user to confirm the bump and its kind before making it — never bump silently, and never skip the question because the answer looks obvious +- **`make patch`, `make minor` and `make major` do the mechanics**, run after the commit is in: each bumps `Cargo.toml` and the `worklane` entry in `Cargo.lock`, appends `, and bump to ` to the commit's subject, folds the bump into that commit, and tags it. Bumping by hand is how a version comes to be left untagged, which is what the one action is for. It refuses on a dirty tree, on an already-tagged `HEAD` and on a `HEAD` that is already pushed, since each of those makes the amend lose work, orphan a tag or need a force push - Pre-1.0, so: patch for fixes and internal changes, minor for a new command, flag or changed output, major only for a deliberate 1.0 - **Changed output means the CLI's output.** That is the surface scripts and agents read, so a changed listing, message or exit code is a minor. A change to what the board draws is a patch however visible it is, since nothing consumes the frame. See The Board View - **Settling output that shipped one version ago is a patch**, not a second minor. 0.15.1 changed the relation mark 0.15.0 had just introduced, and 0.15.2 added the status mark beside it: the minor was the arrival of a marked relations block, and settling what it marks belongs to that. Three minors in an hour would tell anyone reading the tags that there were three features - No bump for docs-only, tests-only or `--fixup` commits - When one body of work spans several commits, bump once on the final commit rather than on each -- Bump `Cargo.toml` and the `worklane` entry in `Cargo.lock` together, in the commit that carries the bump - Every bump gets a matching annotated tag, `v`, on the bump commit — a bumped version is never left untagged - Tag locally only; never push a tag unless asked - `worklane --version` reports the crate version alongside the build sha, so the bump is what makes one release distinguishable from another diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..f7e3bc9 --- /dev/null +++ b/Makefile @@ -0,0 +1,92 @@ +# Release helpers. +# +# `make patch|minor|major` bumps the version in Cargo.toml and Cargo.lock, folds +# that bump into the last commit, and tags it. Everything is one action so a +# release cannot end up half-done: no version bump left untagged, no tag without +# a bump. + +.PHONY: help patch minor major version release install + +help: + @echo "make patch bump $(CURRENT) -> next patch, amend into HEAD, tag" + @echo "make minor bump $(CURRENT) -> next minor, amend into HEAD, tag" + @echo "make major bump $(CURRENT) -> next major, amend into HEAD, tag" + @echo "make version print the current version" + @echo "make install cargo install --path . && worklane install-skill" + +# Read from the [package] table of Cargo.toml, which is the version the binary +# reports through `--version`, so it is the single source of truth. The name is +# what finds this crate's own entry in Cargo.lock. +PACKAGE = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^name *= *"/{print $$2; exit}' Cargo.toml) +CURRENT = $(shell awk -F'"' '/^\[package\]/{p=1;next} /^\[/{p=0} p && /^version *= *"/{print $$2; exit}' Cargo.toml) + +# 1 appends ", and bump to " to the amended commit's subject; empty +# leaves the message alone. +AMEND_SUBJECT = 1 + +version: + @echo $(CURRENT) + +patch: BUMP = patch +minor: BUMP = minor +major: BUMP = major +patch minor major: release + +# A release rewrites the last commit, so refuse anything that would make that +# rewrite lose work or orphan a tag. +release: + @set -e; \ + if ! git rev-parse -q --verify HEAD >/dev/null 2>&1; then \ + echo "error: no commits yet, so there is no commit to fold a version bump into. Commit first." >&2; \ + exit 1; \ + fi; \ + if [ -n "$$(git status --porcelain)" ]; then \ + echo "error: working tree is dirty. Commit or stash first, and decide whether that work belongs in this version:" >&2; \ + git status --short >&2; \ + exit 1; \ + fi; \ + if [ -n "$$(git tag --points-at HEAD)" ]; then \ + echo "error: HEAD is already tagged $$(git tag --points-at HEAD | paste -sd' '). Amending it would leave that tag on an orphaned commit. Commit something first." >&2; \ + exit 1; \ + fi; \ + if upstream=$$(git rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null) && \ + git merge-base --is-ancestor HEAD "$$upstream" 2>/dev/null; then \ + echo "error: HEAD is already pushed to $$upstream. Amending it would need a force push. Commit something first." >&2; \ + exit 1; \ + fi; \ + current="$(CURRENT)"; \ + if [ -z "$$current" ]; then echo "error: no version found in the [package] table of Cargo.toml" >&2; exit 1; fi; \ + new=$$(echo "$$current" | awk -F. -v kind=$(BUMP) '{ \ + if (NF != 3) exit 1; \ + if (kind == "patch") printf "%d.%d.%d\n", $$1, $$2, $$3 + 1; \ + else if (kind == "minor") printf "%d.%d.0\n", $$1, $$2 + 1; \ + else printf "%d.0.0\n", $$1 + 1 }'); \ + if [ -z "$$new" ]; then echo "error: cannot bump version '$$current': expected major.minor.patch" >&2; exit 1; fi; \ + if git rev-parse -q --verify "refs/tags/v$$new" >/dev/null; then \ + echo "error: tag v$$new already exists" >&2; exit 1; \ + fi; \ + awk -v v="$$new" '/^\[package\]/{p=1} /^\[/ && !/^\[package\]/{p=0} p && /^version *= *"/{sub(/"[^"]*"/, "\"" v "\"")} {print}' Cargo.toml > Cargo.toml.bump; \ + mv Cargo.toml.bump Cargo.toml; \ + git add Cargo.toml; \ + if [ -f Cargo.lock ] && git ls-files --error-unmatch Cargo.lock >/dev/null 2>&1; then \ + awk -v v="$$new" -v pkg="$(PACKAGE)" '$$0 == "name = \"" pkg "\""{f=1} f && /^version = "/{sub(/"[^"]*"/, "\"" v "\""); f=0} {print}' Cargo.lock > Cargo.lock.bump; \ + mv Cargo.lock.bump Cargo.lock; \ + git add Cargo.lock; \ + fi; \ + if [ -n "$(AMEND_SUBJECT)" ]; then \ + subject=$$(git log -1 --format=%s | sed -E 's/, and bump to [0-9]+\.[0-9]+\.[0-9]+$$//'); \ + body=$$(git log -1 --format=%b); \ + if [ -n "$$body" ]; then \ + git commit --quiet --amend -m "$$subject, and bump to $$new" -m "$$body"; \ + else \ + git commit --quiet --amend -m "$$subject, and bump to $$new"; \ + fi; \ + else \ + git commit --quiet --amend --no-edit; \ + fi; \ + git tag -a "v$$new" -m "v$$new"; \ + echo "$$current -> $$new, tagged v$$new on $$(git rev-parse --short HEAD) ($$(git log -1 --format=%s))" + +install: + cargo install --path . + worklane install-skill diff --git a/README.md b/README.md index b4363bd..1172852 100644 --- a/README.md +++ b/README.md @@ -78,3 +78,20 @@ Whether a truncated pipe reports 141 or 0 depends on the size of the output, not the command. A pipe holds 64 KiB, so a listing that fits lands in the buffer whole and the writer never learns the reader left, giving 0. Only output past that gets far enough to be cut off. Either way nothing is printed to stderr. + +## Releasing + +```sh +make patch # 0.27.1 -> next patch +make minor # 0.27.1 -> next minor +make major # 0.27.1 -> next major +``` + +Each bumps `Cargo.toml` and `Cargo.lock`, folds that bump into the last commit, and tags it +`v`. One action, so no bump is left untagged and no tag lands without a bump. In this repo +it also appends `, and bump to ` to the commit's subject, the way the release commits +before it read. + +It refuses to run when the working tree is dirty, when `HEAD` is already tagged, or when `HEAD` is +already pushed. The first asks you to decide whether that work belongs in the version; the other two +mean the amend would orphan a tag or need a force push.