Dot Release

Dot Release

Use the checkout's release task as the single owner of preparation and publication. The global [release](../../../skills/git-delivery/references/release/GUIDE.md) skill owns generic versioning and publication verification; this skill owns dot's preconditions and recovery.

Workflow

1. Resolve the mode: preparation, authorized release, or read-only reconciliation. The release command commits, pushes, and refreshes the installed CLI. An explicit /dot-release invocation or release request authorizes the whole flow below, including verification fixes, commits, and the push to main; loading this skill for reference or a review does not.
2. Qualify first: run [dot-verify](../dot-verify/SKILL.md) on the checkout and resolve its findings. Stop and report instead of releasing when a finding needs the user's decision or a gate stays red.
3. Commit the candidate: group verified work into logical [Conventional Commits](../../../skills/git-delivery/references/conventional-commit.md) (the changelog is generated from them), then git fetch and push main so HEAD equals upstream; pre-push hooks rerun the network checks. If upstream moved, integrate it without rewriting history only when its commits do not overlap the candidate; otherwise stop.
4. Inspect preconditions: a clean tree on the configured default branch, gh authenticated, and git, git-cliff, mise, and uv available. Defaults are main and origin; inspect the task's --remote and --branch arguments before assuming them. Preserve unrelated work when a precondition fails.
5. Run the owner: use the commands below from the repository. The task uses uv run --frozen --directory dot python -m dot_tasks.release, avoiding an installed CLI that may lag source. Publication accepts absolute or repository-relative --notes-file paths regardless of uv's working directory.
6. Read the result: a new release requires HEAD equal to the fetched upstream branch. Preparation updates dot/pyproject.toml, CHANGELOG.md, and dot/uv.lock, then runs format, check, test, the starter templates (mise run test:starters, which resolves unlocked upstream packages and must fail before a tag exists), build, and the host completion check (mise run check:completions). Completion generators must succeed for active tools; missing or inactive optional tools are skipped. Only those generated release files may change.
7. Reconcile publication: the command commits, pushes the specific release commit, creates or validates its annotated tag, pushes that exact tag object, and verifies remote acceptance. It then runs mise run --force deploy to refresh the installed dot CLI. A retry revalidates an existing prepared release instead of creating another version.
8. Verify delivery: the tag triggers [cd.yml](../../../.github/workflows/cd.yml): a read-only build job runs the gate, validates the tag plus distribution filenames and internal package/version metadata, and uploads the distributions; an attest job holding only the OIDC and attestation permissions signs them without running repository code; a publish job holding only contents: write revalidates, then publishes. mise run release -- --wait observes the exact head/tag CD and checks public wheel/source assets within --timeout-seconds (default 1800); without it, success reports dispatch only. Follow the global release skill's [verification](../../../skills/git-delivery/references/release/references/verify.md) and [asset checks](../../../skills/git-delivery/references/release/references/verify-assets.md) for deeper artifact and installed-version proof. Local command success does not prove CD completion.

mise run release -- --wait     # interactive release with delivery verification (after dot-verify)
mise run release -- -y --wait  # non-interactive, within an authorized release

Recovery

Inspect git status --short, the release commit, local tag, and remote state before retrying. [release.py](../../../dot/dottasks/release.py) owns recovery; search run_release, _validate_prepared_release, and push_release_tag. Its failure cases are exercised in [testrelease.py](../../../dot/tests/test_release.py).

| Failure boundary | Next action | | -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Before a release commit | The command attempts to restore the version, changelog, and lockfile; commit-stage failures also attempt index recovery. Inspect remaining changes and the original failure before retrying; do not reset unrelated files. | | Commit prepared, branch or tag push incomplete | Reconcile remote acceptance first. A clean prepared commit may equal upstream or be directly one commit ahead; rerunning the authorized release rechecks all six gates before retrying publication. | | Remote publication accepted, installation refresh failed | Verify remote commit/tag and CD independently, then retry mise run --force deploy for the same checkout. An installation error does not undo publication. | | Diverged branch, mismatched tag, or failed recovery | Stop publication retries and report the conflicting state. Do not move published tags, overwrite assets, or rewrite history as an automatic repair. |

Documentation

• [Release workflow test](../../../dot/tests/testreleaseworkflow.py) checks the CD gate before attestation and publication.
• Releases: fmind/dot · changelog
• Companion skills: [dot-verify](../dot-verify/SKILL.md) (pre-release qualification), [dot-development](../dot-development/SKILL.md) (implementation and installation proof), [conventional-commit](../../../skills/git-delivery/references/conventional-commit.md) (commit grammar).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fmind
• Source: fmind/dot
• License: MIT
• Homepage: https://fmind.dev

Install and usage instructions live in the source repository linked above.