Repository navigation
docs(setup): 📝 adopt with existing releases and earlier changelog sections - #28
Merged
Merged
Conversation
robertodr
force-pushed
the
docs/adoption-baseline
branch
from
October 31, 2026 19:08
58e3cd5 to
8819ea3
Compare
2 of 4 tasks
robertodr
force-pushed
the
docs/adoption-baseline
branch
2 times, most recently
from
November 4, 2026 08:44
ae241a5 to
b39b216
Compare
robertodr
force-pushed
the
docs/adoption-baseline
branch
from
November 4, 2026 14:57
b39b216 to
c1ef485
Compare
…ns and release: triggers The baseline is the newest final tag of a repository that released by hand; v0.0.0 only without one. The releases before it go into CHANGELOG.md, generated with git-cliff. Workflows on release: events stop running once GITHUB_TOKEN publishes, and the default branch must be main. Assisted-by: Pi:claude-opus-5-5
… rules Assisted-by: Pi:claude-opus-5-5
robertodr
force-pushed
the
docs/adoption-baseline
branch
from
November 4, 2026 14:59
c1ef485 to
57a9f53
Compare
robertodr
changed the title
robertodr
added a commit
that referenced
this pull request
Nov 5, 2026
🤖 _AI text below_ 🤖 Stacked on #28 (`docs/adoption-baseline`); review only its own commits. Rebase onto `main` once the PRs below it are merged. ## Summary An agent skill for repository admins adopting release-tools: `skills/adopt-release-tools/`. It inspects the repository and GitHub read-only, plans with the admin, writes the adoption PR (stubs, publish workflow, `just changelog`, PR template, `CHANGELOG.md` with the earlier releases, Dependabot), and prepares every command that changes GitHub for the admin to run: no heredocs or placeholders in them, JSON payloads as files, the bot credentials extended one repository at a time. It reads the docs and stubs from a clone of the latest release (or a tag the admin names, e.g. a release candidate for a pilot), so it never carries its own copy. Installed with `npx skills add Algorithmiq/release-tools --skill adopt-release-tools`; documented in docs/adopting.md. `tests/test_skill.py` checks its frontmatter, the major version it is written for, that every release-tools path and heading it reads exists, and that it stops for the admin and hands over only literal commands. Tested with dry runs on internal repositories (not named here), with and without the skill. ## Adversarial review across model tiers The skill was stress-tested for executors weaker than the one that wrote it: Claude Haiku 5.5 and Sonnet 5.5 and GPT-5.6 (Luna, Terra, Sol), from no thinking to high. Each took a 22-question quiz on its decision points (graded against a hidden key), ran it on paper against a hostile CodeArtifact fixture, or reviewed it for clarity and consistency with the docs. The core safety rules held on every model; the failures were where the text left a choice open, and the GPT models answered those with full confidence instead of asking. What changed in the skill: - **Authority:** an explicit list of what the agent runs; it never opens issues or PRs on release-tools (both GPT quiz takers would have); never creates a tag, local or pushed. - **Waits:** a fixed phase-2 message ending in "reply `Plan approved`", and **Stop** points in phases 2, 4, 5 and 6; a command that needs an unanswered value is not handed over but listed under **Waiting for**; one worked example of a handed-over command. - **CodeArtifact:** phase 1 reads the organisation variables' values; an inlined value that differs is a question before phase 3, since the packages would move. With the variables missing, the skill asks an owner which values the organisation uses, then hands over step 5's commands with the answers. - **Workflows:** jobs that ship something for the tag move into the publish workflow; the rest keep their other triggers, with `push: tags` in place of `release`; a build that also runs on PRs is copied; the admin decides whether moved workflows run for pre-release tags. - **Gaps:** stub names already taken, `integration_id` of carried-over checks, querying only the index the repository publishes to, keeping hand-written changelog notes, local `release.py`/`cliff.toml`, re-runs on an open adoption PR. Docs fixed alongside (the skill no longer works around them): - docs/repository-setup.md, step 1: adds the repository to the bot's variable and secret by id, not with `--repos`, which replaces each list. - Step 8: finds every ruleset of `main` through `rules/branches/main`, whatever its name, and adds the PR checks, a `required_status_checks` rule and the bot's bypass only where missing, so a second run changes nothing. Checked against the API on a scratch repository; `tests/test_repository_setup.py` runs its jq. - docs/adopting.md: a `VERSION` file kept in step with the tags next to setuptools-scm goes in `version-files`. Edits were re-checked by rerunning the quiz and the CodeArtifact dry run on GPT-5.6 Luna and Claude Haiku 5.5 at low thinking until they converged. ## Checklist - [ ] Bug fix for the current release: add the `backport` label (or ask a maintainer to) - [x] `just lint` and `just test` pass - [x] docs/adopting.md, docs/organisation-setup.md, and docs/repository-setup.md updated if the stubs, inputs or setup changed - [ ] Breaking change or deprecation: the Migration section says what consumers must change
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
🤖 AI text below 🤖
Stacked on #27 (
feat/codeartifact-stub); review only its own two commits. Rebase ontomainonce the PRs below it are merged.Summary
Per-repository setup for repositories that released by hand before: the baseline is the newest final
vX.Y.Ztag (v0.0.0only without one), with what to do about a dangling pre-release tag or an untagged published version; the releases before the baseline go intoCHANGELOG.md, generated with git-cliff from a worktree at the baseline tag (pinned by a new test intests/test_cliff.py). A new caveat: workflows onrelease:events stop running once releases are published withGITHUB_TOKEN. The default branch must bemain. docs/central-vs-local.md now agrees with the baseline rule.Checklist
backportlabel (or ask a maintainer to)just lintandjust testpass