Skip to content

ci: a behavior-change gate: every PR says if it changes behavior for callers; yes needs '!' and an update note #197

Closed

Description

@groupsky

Why

0.6.0 changed a default that callers depend on (#171: nodkey run masks output when it is not on a terminal, and then stays the parent of the command). It was listed as a plain feature, so nobody who updated got a warning (#191). Before 1.0 a feature and a breaking change both bump the minor version, so the version number does not warn either.

What to build

  1. .github/pull_request_template.md with one required line: Changes behavior for existing callers: yes or no. "Behavior" means defaults, stdout/stderr content, exit codes, signals, which process runs the command, config meaning, and time limits.
  2. A CI check (extend .github/workflows/pr-title.yml or add a job) that fails when:
  3. docs/updating.md: one section per behavior change: who is affected, what to do, a command that shows the new way. Start it with the feat(run): mask fetched values by default; --no-mask turns it off #171 change (from docs: masking by default (#171) breaks password commands and parent checks; show how to handle them with the mask on #191's note in docs/setup.md). docs/releasing.md says how the gate works.
  4. release-please shows ! commits under "⚠ BREAKING CHANGES": check that the squash commit keeps the !, and say so in docs/releasing.md.

The check reads only the PR's title, body and changed file names. It never runs code from the PR.

Done when

Activity

  1. groupsky commented on Nov 17, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-release-ci-1 (run r-20261117-203018-cc7d)

    Done in #208 (merged). #198 is done too, in #209 (merged).

    Done when

    Two points that differ from the issue text

    1. To know that a PR adds an "Updating from X" section, the check also reads the diff of docs/updating.md (only that file) from the GitHub API, as text. It never runs or prints it, and it runs only code from main.
    2. A new *_test.go file right in test/contract/, and a change to test/contract/README.md, do not count as a change in behavior. A new test pins behavior that callers already have. Without this, test: contract tests for how callers use nodkey run #209 (which only adds tests of today's behavior) would have needed !. Any other change there counts: a changed, removed or moved file, and any other new file (such as a go.mod or a file in testdata/).

    The check is in a job that is already required, so no ruleset change is needed. The release PR of release-please and Dependabot PRs that change only dependency files need no answer line.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions