| name | release |
| description | Cut a convertlib release end to end - version choice, CHANGELOG, pubspec bump, atomic release commit, vX.Y.Z tag, push, CI watch, pub.dev verification, and the follow-up dependency bump in ~/projects/hashlib. Use when asked to release, publish, ship, cut a version, or tag. Prevents the tag/pubspec-mismatch failure that killed v3.1.1. |
Release — tag-driven publish to pub.dev
Releases here are fully automated from a tag push: the Release workflow
verifies tag == pubspec version, runs the big matrix (stable/2.19/beta × 3 OS
× vm/node), runs pana at a perfect-score threshold, publishes via OIDC, and
creates a GitHub release from the top CHANGELOG section. Your job is to make
the tag, the pubspec, and the CHANGELOG agree, and to never push a tag that
CI will reject. Never run dart pub publish locally (only --dry-run).
Hard rules
- Version number choice is the owner's call. Propose one with reasoning
(see step 2) and get explicit confirmation before creating the tag.
- Tag,
pubspec.yaml version:, and the top # X.Y.Z CHANGELOG heading must
be identical and on the same commit. v3.1.1 was tagged with a
mismatched state, never published, and had to be re-released as 3.1.2.
- Never move, reuse, or delete a tag. A botched release gets a new patch
version, not a re-tag.
- Do not release with uncommitted changes or from any branch but
master.
Steps
-
Preflight. Run the preflight skill including the release-only steps
(dart pub publish --dry-run and pana). All gates green before proceeding.
-
Determine the version. List what shipped since the last tag:
git describe --tags --abbrev=0
git log --oneline $(git describe --tags --abbrev=0)..HEAD
git diff $(git describe --tags --abbrev=0)..HEAD --stat -- lib/
Semver mapping for this package:
- removed/renamed public symbol, changed output of an existing codec,
SDK floor change → major
- new codec, new alphabet, new public method/class/parameter → minor
- bug fix with no observable-output change, docs, perf → patch
Propose the number to the owner with a one-line justification. Wait for
confirmation.
-
Finalize the CHANGELOG entry. Unreleased changes already sit under a
# _next_ heading at the top of CHANGELOG.md — rename that heading to
# X.Y.Z (if there is no _next_ section, add one). Match house style: -
bullets, backticks around identifiers, breaking changes led by
**Breaking Changes**: with `old` -> `new` rename lists. This text
becomes the GitHub release notes verbatim (CI extracts the top section), so
write it for readers, not for git.
-
Bump pubspec.yaml version: to the same X.Y.Z.
-
Release commit + tag (one atomic unit):
git add CHANGELOG.md pubspec.yaml
git commit -m "Version X.Y.Z"
git tag vX.Y.Z
Before pushing, verify all three agree:
grep '^version:' pubspec.yaml && head -1 CHANGELOG.md && git tag --points-at HEAD
-
Push — after owner confirmation that they want it live now:
git push origin master vX.Y.Z
-
Watch CI to completion. The publish is not done until the workflow is:
gh run list --workflow=release.yml --limit 1
gh run watch <run-id> --exit-status
If the release workflow fails before the publish job, fix the problem on
master and release as a new patch version (do not re-tag). If it fails
after publish succeeded (e.g. the changelog job), the release is live;
fix quietly and note it.
-
Verify on pub.dev:
curl -s https://pub.dev/api/packages/convertlib | python3 -c 'import json,sys; print(json.load(sys.stdin)["latest"]["version"])'
-
Bump the dependent. In ~/projects/hashlib:
pubspec.yaml: convertlib: ^X.Y.Z- bump hashlib's own patch version in the same edit, add its CHANGELOG entry
- commit in hashlib's style, e.g.
Bump version to A.B.C and update convertlib dependency to X.Y.Z
- run
dart pub get && dart test -p vm there before committing; push only
with the owner's go-ahead (hashlib has its own release cadence).
Report
End with: released version, workflow run URL/status, pub.dev latest version,
and the hashlib bump commit (or the reason it was skipped).
