From d686574ed3483a9ccc81e1e800dedb790bd3c163 Mon Sep 17 00:00:00 2001 From: Geno Roupsky <185580+groupsky@users.noreply.github.com> Date: Tue, 17 Nov 2026 20:39:56 +0200 Subject: [PATCH 1/2] ci: a behavior-change gate: every PR says if it changes behavior for callers Fixes #197 Co-Authored-By: Claude Opus 5.5 --- .github/pull_request_template.md | 27 +++ .github/workflows/pr-title.yml | 40 +++- .golangci.yml | 6 + AGENTS.md | 13 +- DESIGN.md | 10 + docs/releasing.md | 86 ++++++++- docs/setup.md | 5 + docs/updating.md | 66 +++++++ tools/prgate/main.go | 297 ++++++++++++++++++++++++++++++ tools/prgate/main_test.go | 307 +++++++++++++++++++++++++++++++ 10 files changed, 853 insertions(+), 4 deletions(-) create mode 100644 .github/pull_request_template.md create mode 100644 docs/updating.md create mode 100644 tools/prgate/main.go create mode 100644 tools/prgate/main_test.go diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..b884df6 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,27 @@ +## What and why + + + +## Behavior for callers + + + +Changes behavior for existing callers: yes or no + +## Tests + + diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml index b085a4d..f37af91 100644 --- a/.github/workflows/pr-title.yml +++ b/.github/workflows/pr-title.yml @@ -7,12 +7,16 @@ name: PR title on: # pull_request_target also runs for pull requests from forks. It runs with # this repository's token, so this workflow must never check out or run - # code from the pull request. It only reads the title. + # code from the pull request. It reads only the title, the description, + # and the list of changed files. It checks out and runs code from the + # base branch (main) only. + # "edited" covers a new title and a new description. pull_request_target: types: [opened, edited, synchronize, reopened] permissions: - pull-requests: read # read the pull request + contents: read # check out main, for the behavior-change gate + pull-requests: read # read the pull request and its changed files concurrency: # Check only the newest title of a pull request. @@ -41,3 +45,35 @@ jobs: refactor build style + # The behavior-change gate (docs/releasing.md, "Changes in behavior + # for callers"). It is in this job, so it is a required check too. + - name: Check out main, not the pull request + # Run the gate also when the title check failed, so the author + # sees both results at once. + if: ${{ !cancelled() }} + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + # For pull_request_target, github.sha is the newest commit of the + # base branch. Never use a ref or a SHA of the pull request here. + ref: ${{ github.sha }} + persist-credentials: false + - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0 + if: ${{ !cancelled() }} + with: + go-version-file: go.mod + # No cache in a pull_request_target run. + cache: false + - name: Behavior change for callers + if: ${{ !cancelled() }} + env: + TOKEN: ${{ github.token }} + PR_NUMBER: ${{ github.event.pull_request.number }} + run: | + set -euo pipefail + files="${RUNNER_TEMP}/changed-files.jsonl" + # Keep the names of all files, and the diff of docs/updating.md + # only. Only gh gets the token. + GH_TOKEN="$TOKEN" gh api --paginate "repos/${GITHUB_REPOSITORY}/pulls/${PR_NUMBER}/files" \ + --jq '.[] | {filename, previous_filename, patch: (if .filename == "docs/updating.md" then .patch else null end)}' > "$files" + unset TOKEN + go run ./tools/prgate --event "$GITHUB_EVENT_PATH" --files "$files" diff --git a/.golangci.yml b/.golangci.yml index 9b74508..a94231a 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -62,6 +62,12 @@ linters: linters: - forbidigo text: library code must not + # tools/ holds programs for CI, such as the behavior-change gate + # (tools/prgate). They are commands too, and may print. + - path: ^tools/ + linters: + - forbidigo + text: library code must not # os.ReadFile is forbidden only in library code under internal/. The # config package has the file readers, and tests read their own files. - path-except: ^internal/ diff --git a/AGENTS.md b/AGENTS.md index 44aee31..10163b9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -78,7 +78,10 @@ Planned. Each v1 issue adds its part. - `docs/manual-ntfy-test.md` - the manual test with a real ntfy server, on Android and on an iPhone (issue #24), with a table for the results. - - `docs/releasing.md` - how releases are made and checked. + - `docs/releasing.md` - how releases are made and checked, and the + behavior-change gate. + - `docs/updating.md` - one section per change in behavior for callers + ("## Updating from X"): who is affected, what to do, a command. - `docs/agent-browser.md` - website logins with agent-browser: the plugin entry, the login steps and the `agents` Chrome profile. - `docs_test.go` (at the root of the module) checks that no shell @@ -87,6 +90,9 @@ Planned. Each v1 issue adds its part. - `test/e2e/` - the end-to-end test with `sshd` in a container (DESIGN.md section 17). Build tag `e2e`. The image of the container is `test/e2e/testdata/sshd`. +- `tools/prgate/` - the behavior-change gate that the PR title workflow + runs from `main` (docs/releasing.md, "Changes in behavior for + callers"). `.github/pull_request_template.md` has its line. - `.claude/agents/security-reviewer.md` - the security review every change gets. @@ -138,6 +144,11 @@ that it makes. titles follow [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, `test:`, `ci:`, `chore:`). Pull requests are squash merged. Never push to `main` directly. +- **Every pull request description** has the line + `Changes behavior for existing callers: yes` or `no`. For `yes`, the + title has `!` (`feat(run)!: ...`) and the pull request adds a section + `## Updating from X` to `docs/updating.md`. A change under + `test/contract/` is always `yes`. CI checks it (docs/releasing.md). - **Open work is a GitHub issue** with a "Done when" checklist, never a TODO file. - **Every error says how to fix it.** Every error that a person or an diff --git a/DESIGN.md b/DESIGN.md index 686726e..f077d3c 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -4578,6 +4578,16 @@ Infisical SDK in the broker (section 4, `internal/store/infisical.go`): - GitHub Actions are pinned to a commit SHA. - Pull request titles follow Conventional Commits. Pull requests are squash merged. +- Every pull request says if it changes behavior for existing callers + (defaults, stdout and stderr, exit codes, signals, which process runs + the command, config meaning, time limits). For `yes`, the title has `!`, + so release-please lists it under "⚠ BREAKING CHANGES", and the pull + request adds a section to `docs/updating.md`. A change under + `test/contract/` is always `yes`. `tools/prgate` checks this in the PR + title workflow, run from `main` with `pull_request_target`; it reads + only the title, the description, the author, the branch name and the + changed files (names, and the added lines of `docs/updating.md`), and + never runs code of the pull request. See docs/releasing.md. - Pull request titles may use the type `security` (also `security(deps)`) for a real security fix. It puts a `### Security` section first in CHANGELOG.md and in the release notes; a line may name advisory IDs diff --git a/docs/releasing.md b/docs/releasing.md index ff43f81..9e6ceb6 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -30,6 +30,88 @@ For a breaking change, add `!` after the type. For example: The **PR title** check tests the title. If the check fails, edit the title. The check runs again by itself. +## Changes in behavior for callers + +Before 1.0, a feature and a breaking change both make a minor release +(see [Versions before 1.0](#versions-before-10)). So the version number +does not warn the people who update. 0.6.0 changed a default that +programs and scripts depend on (#171), and it was listed as a normal +feature (#191). This gate makes such a change visible. + +### The line in the description + +The description of every pull request has this line, with `yes` or `no` +([`.github/pull_request_template.md`](../.github/pull_request_template.md)): + +```text +Changes behavior for existing callers: no +``` + +"Behavior" means: defaults, the content of stdout and stderr, exit codes, +signals, which process runs the command, the meaning of the config, and +time limits. A program or a script that uses nodkey can break when one +of them changes. + +For `yes`, the pull request must also: + +- have `!` after the type or the scope of the title, for example + `feat(run)!: mask the output by default`; +- add a section `## Updating from X` to + [docs/updating.md](updating.md). It says who is affected, what to do, + and gives a command that shows the new way. `X` is the newest release + that still has the old behavior, for example `0.5.0 or older`. + +### The check + +The **PR title** workflow runs the check in its job +**Conventional Commits title**, after the title check. This job is +already a required check of `main`. The check fails when: + +- the line is missing, is there more than once, or has another value + than `yes` or `no` (in small letters, with nothing else; a line in an + HTML comment `` does not count); +- the answer is `yes` and the title has no `!`; +- the answer is `yes` and the pull request adds no line + `## Updating from X` to `docs/updating.md`; +- the answer is `no` and the title has a `!`; +- the pull request changes a file under `test/contract/` and the answer + is `no`. These tests pin what callers see, so a change to one of them + is a change in behavior for callers. + +The error says what to fix. Edit the title or the description: the +check runs again by itself. + +Two kinds of pull requests need no line: + +- the release pull request of release-please: its author is the release + App, its branch is `release-please--branches--main`, and it changes + only `CHANGELOG.md` and `.release-please-manifest.json`. Its commits + passed the check one by one; +- a pull request of Dependabot with no `!` in the title that changes + only `go.mod`, `go.sum`, files under `.github/workflows/` and files + under `test/e2e/testdata/sshd/`. + +The check is `tools/prgate`, with its tests in +`tools/prgate/main_test.go`. The workflow runs it with +`pull_request_target`, from the code on `main`, never from the pull +request. It reads only the title, the description, the author and the +branch name of the pull request, and the list of changed files from the +GitHub API: their names, and the diff of `docs/updating.md` only, as +text. It never prints text of the pull request to the log. A change to +the check itself takes effect only after it is merged. + +### "⚠ BREAKING CHANGES" in the release notes + +release-please lists a commit with `!` after the type or the scope under +**⚠ BREAKING CHANGES**, at the top of the release notes and of +CHANGELOG.md. The commit on `main` must keep the `!`. It does: the +squash commit takes the pull request title as its message (repository +setting: the default commit message of a squash merge is the pull +request title; checked on 2026-11-17). So never change the title in the +merge dialog, and never remove the `!` from it. Before you merge a +release pull request, check that each change of `docs/updating.md` since +the last release has its line under **⚠ BREAKING CHANGES**. + ## Security fixes Use the type `security` for a pull request that fixes a real security @@ -173,7 +255,9 @@ without activity. If this happens, turn on the CI workflow again in the These settings protect `main` and the releases: - **Ruleset for `main`**: changes only through a pull request; the CI checks - and the PR title check must pass; no force push; `main` cannot be deleted. + and the PR title check (with the gate of + [Changes in behavior for callers](#changes-in-behavior-for-callers)) + must pass; no force push; `main` cannot be deleted. - **Rulesets for `v*` tags**: nobody can move or delete a tag, not even the release App. Only the release App can create one. - **Immutable releases**: on. diff --git a/docs/setup.md b/docs/setup.md index 3809505..81c6ec4 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -2749,6 +2749,11 @@ such as a password command, and each script that checks its parent. [Section 11, "Keep the mask on"](#keep-the-mask-on-password-commands-and-wrappers) shows how to change them, with the mask still on. +**Changes in behavior.** [docs/updating.md](updating.md) lists each +change that can break a program or a script that uses nodkey, with what +to do. Read its sections from your version up to the new one before you +update. + ### New versions of bws and bw Install them in the same way as the first time diff --git a/docs/updating.md b/docs/updating.md new file mode 100644 index 0000000..eda510f --- /dev/null +++ b/docs/updating.md @@ -0,0 +1,66 @@ +# Updating nodkey + +This page lists each change in nodkey that can break a program or a +script that uses it: a new default, other output on stdout or stderr, a +new exit code, other signals, another process that runs the command, a +new meaning of a config key, or a new time limit. Before you update, +read every section from your version up to the new one. + +Each section says who is affected, what to do, and gives a command that +shows the new way. The steps of an update itself are in +[docs/setup.md, section 13](setup.md#13-upgrades-and-key-changes). + +From 2026-11-17 on, the release notes list such a change under +"⚠ BREAKING CHANGES", and its pull request adds a section here +([docs/releasing.md](releasing.md#changes-in-behavior-for-callers)). +Older releases listed it as a normal feature. + +## Updating from 0.5.0 or older + +**What changed (0.6.0, #171).** `nodkey run` masks the values that it +fetched: it replaces each one with `***` in the command's stdout and +stderr. This is now the default whenever stdout or stderr of +`nodkey run` is not a terminal. A masked `nodkey run` stays as the parent +of the command: it does not replace itself with the command, as 0.5.0 +did. On a terminal (stdout and stderr both a terminal), nothing changed. + +**Who is affected.** + +- A program that reads the output of `nodkey run` through a pipe, such + as a mail client with a password command like + `nodkey run --secret P=mail-read -- printenv P`. It now gets `***`, and + its login fails. +- A script that checks that its parent is the process that started + `nodkey run`. Its parent is now a process named `nodkey`. + +**What to do.** Keep the mask on. With `--no-mask`, even a plain +`printenv` or a debug line of the command shows the value. + +- For a password command: run the program itself inside `nodkey run`, + and let its password command read the value from the program's own + environment. For example, with `password.cmd = "printenv MAIL_READ"` in + the program's config: + + ```sh + nodkey run --secret MAIL_READ=mail-read --reason "read the mail" -- mail-client sync + ``` + +- For a parent check: accept a parent named `nodkey`, and look at that + process's parent. nodkey is not dumpable, so read `/proc/PID/stat`, not + `/proc/PID/exe`: + + ```sh + parent=$PPID + name=$(sed 's/^[0-9]* (\(.*\)) .*/\1/' "/proc/$parent/stat") + if [ "$name" = nodkey ]; then + parent=$(awk '{print $4}' "/proc/$parent/stat") + fi + ``` + + A process name is not proof: any program of the same user can take + the name `nodkey`. Use this only where the parent check is a + convenience, not a security boundary. + +The full text, with what a masked command gets (stdin, file descriptors) +and the risks of each way, is in +[docs/setup.md, "Keep the mask on"](setup.md#keep-the-mask-on-password-commands-and-wrappers). diff --git a/tools/prgate/main.go b/tools/prgate/main.go new file mode 100644 index 0000000..61453c8 --- /dev/null +++ b/tools/prgate/main.go @@ -0,0 +1,297 @@ +// Command prgate is the behavior-change gate for pull requests (issue +// #197, docs/releasing.md "Changes in behavior for callers"). +// +// Every pull request body has the line +// +// Changes behavior for existing callers: yes +// +// or the same line with "no". prgate fails when: +// - the line is missing, is there more than once, or has another value; +// - the answer is "yes" and the title has no "!" (such as "feat(run)!: ..."); +// - the answer is "yes" and the pull request adds no "## Updating from X" +// section to docs/updating.md; +// - the answer is "no" and the title has a "!"; +// - the pull request changes a file under test/contract/ and the answer +// is "no". +// +// The workflow runs prgate from main, never from the pull request. prgate +// reads only the event file of GitHub (title, body, author, branch name, +// number of changed files) and the list of changed files from the GitHub +// API (names, and the added lines of docs/updating.md as text). It never +// prints the title, the body or a file name: the author chose that text, +// and a line such as "::stop-commands::" in the log is a command to the +// runner. +package main + +import ( + "encoding/json" + "errors" + "flag" + "fmt" + "io" + "os" + "regexp" + "strings" +) + +const ( + exitOK = 0 + exitFail = 1 + exitUsage = 2 + + answerPrefix = "Changes behavior for existing callers:" + contractDir = "test/contract/" + updatingFile = "docs/updating.md" + + // The release pull request of release-please only collects commits + // that passed this gate one by one. + releaseBot = "code6x-release[bot]" + releaseBranch = "release-please--branches--main" + dependabotBot = "dependabot[bot]" +) + +// The files that a release pull request may change. +var releaseFiles = map[string]bool{ + "CHANGELOG.md": true, + ".release-please-manifest.json": true, +} + +// The files that Dependabot changes for this repository +// (.github/dependabot.yml): Go modules, GitHub Actions and the image of +// the end-to-end test. +func dependabotFile(name string) bool { + return name == "go.mod" || name == "go.sum" || + strings.HasPrefix(name, ".github/workflows/") || + strings.HasPrefix(name, "test/e2e/testdata/sshd/") +} + +var ( + // A Conventional Commits title of a breaking change: "feat!: ..." or + // "feat(run)!: ...". Only these forms make release-please list the + // commit under "⚠ BREAKING CHANGES". + breakingTitle = regexp.MustCompile(`^[a-z]+(\([^()\r\n]*\))?!: `) + answerLine = regexp.MustCompile(`(?m)^[ \t]*` + regexp.QuoteMeta(answerPrefix) + `[ \t]*(.*?)[ \t]*$`) + htmlComment = regexp.MustCompile(`(?s)|\z)`) + updatingHead = regexp.MustCompile(`^## Updating from \S`) +) + +// pullRequest is what prgate reads from the event of GitHub. +type pullRequest struct { + Title string `json:"title"` + Body string `json:"body"` + ChangedFiles int `json:"changed_files"` + User struct { + Login string `json:"login"` + Type string `json:"type"` + } `json:"user"` + Head struct { + Ref string `json:"ref"` + } `json:"head"` +} + +// changedFile is one entry of GET /repos/{owner}/{repo}/pulls/{n}/files. +type changedFile struct { + Filename string `json:"filename"` + PreviousFilename string `json:"previous_filename"` + Patch *string `json:"patch"` +} + +func main() { + os.Exit(run(os.Args[1:], os.Stdout, os.Stderr)) +} + +func run(args []string, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("prgate", flag.ContinueOnError) + fs.SetOutput(io.Discard) + eventPath := fs.String("event", "", "") + filesPath := fs.String("files", "", "") + if err := fs.Parse(args); err != nil || *eventPath == "" || *filesPath == "" || fs.NArg() != 0 { + _, _ = fmt.Fprintln(stderr, `prgate: give --event FILE (the GitHub event) and --files FILE (JSON lines of the changed files); see .github/workflows/pr-title.yml (exit 2)`) + return exitUsage + } + pr, err := readEvent(*eventPath) + if err != nil { + _, _ = fmt.Fprintf(stderr, "prgate: %v (exit 2)\n", err) + return exitUsage + } + files, err := readFiles(*filesPath) + if err != nil { + _, _ = fmt.Fprintf(stderr, "prgate: %v (exit 2)\n", err) + return exitUsage + } + if len(files) != pr.ChangedFiles { + _, _ = fmt.Fprintf(stderr, "prgate: the pull request changes %d files, but the GitHub API listed %d; GitHub lists at most 3000. Split the pull request, or push again to run the check again (exit 1)\n", + pr.ChangedFiles, len(files)) + return exitFail + } + note, problems := check(pr, files) + if len(problems) > 0 { + for _, p := range problems { + _, _ = fmt.Fprintf(stderr, "prgate: %s\n", p) + } + _, _ = fmt.Fprintln(stderr, `prgate: see docs/releasing.md, "Changes in behavior for callers" (exit 1)`) + return exitFail + } + _, _ = fmt.Fprintf(stdout, "prgate: ok: %s\n", note) + return exitOK +} + +func readEvent(path string) (pullRequest, error) { + data, err := os.ReadFile(path) //nolint:gosec // G304: the event file that GitHub names in GITHUB_EVENT_PATH. + if err != nil { + return pullRequest{}, fmt.Errorf("cannot read the event file: %w; the workflow must pass GITHUB_EVENT_PATH", err) + } + var event struct { + PullRequest *pullRequest `json:"pull_request"` + } + if err := json.Unmarshal(data, &event); err != nil { + return pullRequest{}, fmt.Errorf("the event file is not valid JSON: %w; run the check only on pull_request_target events", err) + } + if event.PullRequest == nil { + return pullRequest{}, errors.New("the event file has no pull_request; run the check only on pull_request_target events") + } + return *event.PullRequest, nil +} + +func readFiles(path string) ([]changedFile, error) { + f, err := os.Open(path) //nolint:gosec // G304: the file that the workflow wrote with gh api. + if err != nil { + return nil, fmt.Errorf("cannot read the list of changed files: %w; the workflow must write it with gh api", err) + } + defer func() { _ = f.Close() }() + dec := json.NewDecoder(f) + var files []changedFile + for { + var cf changedFile + err := dec.Decode(&cf) + if errors.Is(err, io.EOF) { + return files, nil + } + if err != nil { + return nil, fmt.Errorf("the list of changed files is not valid JSON: %w; the workflow must write it with gh api --jq", err) + } + if cf.Filename == "" { + return nil, errors.New("an entry in the list of changed files has no file name; the workflow must write it with gh api --jq") + } + files = append(files, cf) + } +} + +// check returns a short note when the pull request passes, or the +// problems that make it fail. No problem quotes text of the pull request. +func check(pr pullRequest, files []changedFile) (string, []string) { + touchesContract := false + for _, f := range files { + if strings.HasPrefix(f.Filename, contractDir) || strings.HasPrefix(f.PreviousFilename, contractDir) { + touchesContract = true + } + } + if isBot(pr, releaseBot) && pr.Head.Ref == releaseBranch && onlyReleaseFiles(files) { + return "the release pull request of release-please needs no answer", nil + } + breaking := breakingTitle.MatchString(pr.Title) + if isBot(pr, dependabotBot) && !breaking && onlyDependabotFiles(files) { + return "a Dependabot pull request that changes only dependency files needs no answer", nil + } + + answer, problem := parseAnswer(pr.Body) + if problem != "" { + return "", []string{problem} + } + + var problems []string + switch answer { + case "yes": + if !breaking { + problems = append(problems, `the answer is "yes", but the title has no "!": add it after the type or the scope, such as "feat(run)!: ...", so that release-please lists the change under "⚠ BREAKING CHANGES"`) + } + if !addsUpdatingNote(files, &problems) { + problems = append(problems, `the answer is "yes", but the pull request adds no "## Updating from X" section to `+updatingFile+`: add one that says who is affected, what to do, and a command that shows the new way`) + } + case "no": + if breaking { + problems = append(problems, `the title has a "!" (a breaking change), but the answer is "no": answer "yes" and add a note to `+updatingFile+`, or take the "!" out of the title`) + } + if touchesContract { + problems = append(problems, `the pull request changes a file under `+contractDir+`, but the answer is "no": a change to a contract test is a change in behavior for callers; answer "yes", add "!" to the title and a note to `+updatingFile) + } + } + if len(problems) > 0 { + return "", problems + } + return fmt.Sprintf("changes behavior for existing callers: %s", answer), nil +} + +// isBot reports whether the author is the GitHub App with this login. A +// person cannot have a login that ends in "[bot]", and the type says +// "Bot" only for an App. +func isBot(pr pullRequest, login string) bool { + return pr.User.Type == "Bot" && pr.User.Login == login +} + +func onlyDependabotFiles(files []changedFile) bool { + if len(files) == 0 { + return false + } + for _, f := range files { + if !dependabotFile(f.Filename) || (f.PreviousFilename != "" && !dependabotFile(f.PreviousFilename)) { + return false + } + } + return true +} + +func onlyReleaseFiles(files []changedFile) bool { + if len(files) == 0 { + return false + } + for _, f := range files { + if !releaseFiles[f.Filename] || (f.PreviousFilename != "" && f.PreviousFilename != f.Filename) { + return false + } + } + return true +} + +// parseAnswer finds the one answer line in the body, outside HTML +// comments, and returns "yes" or "no", or a problem. +func parseAnswer(body string) (string, string) { + body = strings.ReplaceAll(body, "\r\n", "\n") + body = htmlComment.ReplaceAllString(body, "") + matches := answerLine.FindAllStringSubmatch(body, -1) + switch { + case len(matches) == 0: + return "", `the description has no line "` + answerPrefix + ` yes" or "... no": add it as in .github/pull_request_template.md` + case len(matches) > 1: + return "", `the description has the line "` + answerPrefix + `" more than once: keep one` + } + switch v := matches[0][1]; v { + case "yes", "no": + return v, "" + default: + return "", `the line "` + answerPrefix + `" must end in "yes" or "no", in small letters and with nothing else: edit the description` + } +} + +// addsUpdatingNote reports whether the patch of docs/updating.md adds a +// line "## Updating from X". It adds a problem when GitHub sent no patch. +func addsUpdatingNote(files []changedFile, problems *[]string) bool { + for _, f := range files { + if f.Filename != updatingFile { + continue + } + if f.Patch == nil { + *problems = append(*problems, `GitHub sent no diff of `+updatingFile+` (it is too large or binary): make the change of this file smaller`) + return true + } + for _, line := range strings.Split(*f.Patch, "\n") { + if strings.HasPrefix(line, "+++") || !strings.HasPrefix(line, "+") { + continue + } + if updatingHead.MatchString(strings.TrimSuffix(line[1:], "\r")) { + return true + } + } + } + return false +} diff --git a/tools/prgate/main_test.go b/tools/prgate/main_test.go new file mode 100644 index 0000000..93cc7b9 --- /dev/null +++ b/tools/prgate/main_test.go @@ -0,0 +1,307 @@ +package main + +import ( + "bytes" + "encoding/json" + "os" + "path/filepath" + "strings" + "testing" +) + +func ptr(s string) *string { return &s } + +func newPR(title, body string) pullRequest { + var pr pullRequest + pr.Title = title + pr.Body = body + pr.User.Login = "someone" + pr.User.Type = "User" + pr.Head.Ref = "feature" + return pr +} + +const ( + bodyNo = "Fixes #1\n\nChanges behavior for existing callers: no\n" + bodyYes = "Fixes #1\n\nChanges behavior for existing callers: yes\n" +) + +var ( + codeFile = changedFile{Filename: "internal/client/run.go", Patch: ptr("@@ -1 +1 @@\n-a\n+b")} + updatingNote = changedFile{Filename: "docs/updating.md", Patch: ptr("@@ -1,2 +1,8 @@\n # Updating nodkey\n \n+## Updating from 0.7.0 or older\n+\n+Who is affected: ...")} + contractFile = changedFile{Filename: "test/contract/pipe_test.go", Patch: ptr("@@ -1 +1 @@\n-a\n+b")} +) + +func TestCheck(t *testing.T) { + type tc struct { + name string + pr pullRequest + files []changedFile + pass bool + reason string // a part of the problem, for a fail + } + tests := []tc{ + // Pass. + {name: "no", pr: newPR("fix: a bug", bodyNo), files: []changedFile{codeFile}, pass: true}, + {name: "yes with ! and note", pr: newPR("feat(run)!: new default", bodyYes), files: []changedFile{codeFile, updatingNote}, pass: true}, + {name: "yes without scope", pr: newPR("feat!: new default", bodyYes), files: []changedFile{updatingNote}, pass: true}, + {name: "contract change with yes", pr: newPR("test!: pin the pipe", bodyYes), files: []changedFile{contractFile, updatingNote}, pass: true}, + {name: "CRLF body", pr: newPR("fix: a bug", "a\r\nChanges behavior for existing callers: no\r\nb"), files: []changedFile{codeFile}, pass: true}, + {name: "spaces around answer", pr: newPR("fix: a bug", " Changes behavior for existing callers: no \n"), files: []changedFile{codeFile}, pass: true}, + {name: "line in a comment is ignored", pr: newPR("fix: a bug", "\nChanges behavior for existing callers: no"), files: []changedFile{codeFile}, pass: true}, + + // Fail: the line is missing or has another value. + {name: "empty body", pr: newPR("fix: a bug", ""), files: []changedFile{codeFile}, reason: "has no line"}, + {name: "missing", pr: newPR("fix: a bug", "Fixes #1"), files: []changedFile{codeFile}, reason: "has no line"}, + {name: "only in a comment", pr: newPR("fix: a bug", ""), files: []changedFile{codeFile}, reason: "has no line"}, + {name: "only in an open comment", pr: newPR("fix: a bug", "