Skip to content

Propose updates through one rolling pull request for adopters who opt in

Supersedes ADR 0014 for adopters who opt in. Under ADR 0014 an update ran only when someone asked for one. With releases as frequent as they are, adopters fell behind or spent time on every routine update, and nothing brought an update to them for review the way a dependency bot does. As settled in decisions 3, 7, 9 and 10 of the #281 grilling outcome and specified in #330, Repository Standards publishes a composite GitHub action, action.yml at the repository root, that keeps an adopting repository current through one rolling pull request or one rolling issue.

An adopter opts in by installing a caller workflow that runs the action, such as the one Repo Canon installs. Installing it is the maintainer’s standing instruction to propose every available update. Without it, ADR 0014 holds: the update notice states availability and an update starts only on the maintainer’s instruction.

Each run checks the pins with the pinned outdated --json and, when either has an update, runs the newest published CLI’s adopt --headless --json, so both pins move together, always to the newest CLI. A complete update is committed on the one rolling branch, repo-standards/update, force-pushed, and proposed as an adoption pull request whose body is the adoption record and whose title follows the adoption rule. A pin moving by a major version, or by a minor version of a 0.x pin, makes the title breaking, with Impact and Migration sections. A headless update that stops opens one rolling issue with its open questions instead, unless an optional agent command finishes it. A newer release refreshes the open item; the same release leaves it untouched; landing or superseding the update closes it.

This amends the architecture and glossary:

  • The architecture’s explicit exclusions allow the action’s commits on its own rolling branch and its rule for available updates; the CLI still makes no commit, push, branch, pull request or issue.
  • Roles name the action as the product repository’s, and the adopting project’s caller workflow as its opt-in.
  • An Update stays deliberate: the opt-in is the deliberate decision, and merging the pull request remains the maintainer’s. The Update notice leaves every update to the maintainer except those the opt-in requests.
  • Keep ADR 0014 for everyone. Routine updates keep costing every adopter a manual run.
  • Start every available update by default. ADR 0014 rejected this, and it still holds without an opt-in: the maintainer would review work they had not asked for.
  • Let the CLI commit and open the pull request. That would put forge code and commits into a CLI whose contract is that it never commits, for every caller, to serve one workflow.
  • A pull request per release. Several open update proposals would compete and each go stale; one rolling item always carries the newest release.

All forge-specific code sits in one module of the action, which a forge seam can later replace. GITHUB_TOKEN is only a fallback: pull requests it opens trigger no workflow runs, and it cannot push changes to workflow files, so a refused push opens the rolling issue naming the reason. Remote setup stays deferred by the headless update, and the next local adopt applies it. Merging stays the maintainer’s: the action never merges.