From 511daec5a86489d4da609d8108bfd7e4d9e2a89e Mon Sep 17 00:00:00 2001 From: Kris Hicks Date: Fri, 23 Oct 2026 07:24:04 -0700 Subject: [PATCH] docs(contributing): exempt build and flaky-test fixes from the issue requirement Prior to this change, CONTRIBUTING.md, the PR template, and the create-github-pr skill required every PR except automated dependency updates to close an issue. A maintainer fixing a broken build or flaky tests had to file an issue that only restated the failure the PR already describes. Now, authors with WRITE, MAINTAIN, or ADMIN access may open a PR that only fixes a broken build or flaky tests without a separate issue, and describe the failure in the PR instead. Authors without write access still need an accepted issue; the PR Issue Acceptance workflow already passes write-access authors without checking for linked issues, so it needs no change. The branch naming rule now covers PRs without an issue, and the sync-agent-infra consistency check states the new rule. Signed-off-by: Kris Hicks --- .agents/skills/create-github-pr/SKILL.md | 4 ++-- .agents/skills/sync-agent-infra/SKILL.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CONTRIBUTING.md | 6 ++++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.agents/skills/create-github-pr/SKILL.md b/.agents/skills/create-github-pr/SKILL.md index f564bd8d00..59ab0dade0 100644 --- a/.agents/skills/create-github-pr/SKILL.md +++ b/.agents/skills/create-github-pr/SKILL.md @@ -13,7 +13,7 @@ Create pull requests on GitHub using the `gh` CLI. - The `gh` CLI must be authenticated (`gh auth status`) - You must have commits on a branch that's pushed to the remote -- Every PR must close an existing issue, except automated dependency updates as described in `CONTRIBUTING.md`. Follow Branch Names in `CONTRIBUTING.md` for contributor branch names. +- Every PR must close an existing issue, except automated dependency updates and build or flaky-test fixes from authors with write access, as described in `CONTRIBUTING.md`. Follow Branch Names in `CONTRIBUTING.md` for contributor branch names. ## Before Creating a PR @@ -126,7 +126,7 @@ gh pr create --title "PR title" --body "PR description" ### Link to an Issue -Every PR except an automated dependency update must close its own issue. Verify that the issue exists, remains open, and covers the PR scope. Automated dependency updates follow the exception in `CONTRIBUTING.md`. Use `Closes #` in the body so merge closes it: +Every PR must close its own issue, except automated dependency updates and build or flaky-test fixes from authors with write access; both follow the exceptions in `CONTRIBUTING.md`. A PR without an issue describes the failure it fixes in the Related Issue section. Otherwise, verify that the issue exists, remains open, and covers the PR scope. Use `Closes #` in the body so merge closes it: ```bash gh pr create \ diff --git a/.agents/skills/sync-agent-infra/SKILL.md b/.agents/skills/sync-agent-infra/SKILL.md index 5f2a843197..d06ebbb277 100644 --- a/.agents/skills/sync-agent-infra/SKILL.md +++ b/.agents/skills/sync-agent-infra/SKILL.md @@ -41,7 +41,7 @@ Search both `skills/` and `.agents/skills/` for affected commands, fields, and c 2. Compare `crates/` with the architecture table in `AGENTS.md`. Check the public and contributor skill rows. 3. Follow Label Discovery in `CONTRIBUTING.md` to retrieve every page of current GitHub labels and resolve unclear descriptions, then check issue guidance for the general triage → validation → human acceptance process. Skills should mention the `state:*` namespace without enumerating exact labels, and should not depend on `agent:*` labels. A direct request authorizes only the requested phase; unattended work uses current state descriptions, maintainer assignments, and comments to establish the authorized phase. 4. Check issue templates, `create-github-issue`, `create-spike`, and `triage-issue` for the first-hand OpenShell User Story, OpenShell-only bug reproduction, notional UX examples, and consideration of applicable extension points. -5. Check the PR template, `create-github-pr`, `build-from-issue`, `fix-security-issue`, and `CONTRIBUTING.md`: every PR must close an existing issue covering its scope, except automated dependency updates as described in `CONTRIBUTING.md`. Multi-PR work needs an issue per PR; a separate issue may track the overall effort. +5. Check the PR template, `create-github-pr`, `build-from-issue`, `fix-security-issue`, and `CONTRIBUTING.md`: every PR must close an existing issue covering its scope, except automated dependency updates and build or flaky-test fixes from authors with write access, as described in `CONTRIBUTING.md`. Multi-PR work needs an issue per PR; a separate issue may track the overall effort. 6. Check contributor branch instructions and examples against Branch Names in `CONTRIBUTING.md`; AGENTS.md and skills should refer to that convention. Check `README.md`, `.github/ISSUE_TEMPLATE/`, `.github/workflows/`, `.agents/agents/`, and related skill cross references for stale workflow statements. Keep user-facing documentation changes minimal and avoid duplicated internal explanations. 7. Check that PR, build, TUI, and docs contribution guidance follow the scoped verification guidance in `CONTRIBUTING.md`; they must not require full Rust, SDK, or repository CI for changes that cannot affect those areas. 8. Use `npx -y skills add . --list` from a disposable clean copy when skill discovery changes. It should expose public skills only; clean generated files afterward. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5cb3dd2efd..85a27e38f7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -2,7 +2,7 @@ ## Related Issue - + ## Changes diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4dfea77b67..33495d9153 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -403,7 +403,7 @@ Issues and pull requests receive `state:stale` after 14 days without activity. O For release notes, describe the user-facing change in a few short, easy-to-read sentences in the optional **Release Notes** section of the PR description. Keep the section concise. Stable releases use it when non-empty; otherwise they summarize the PR title and description. -Every PR except an automated dependency update must close an existing issue. In the PR's **Related Issue** section, use `Closes #NNN` for the issue covering that PR's scope. Split multi-PR work into a closable issue for each PR; a tracking issue can link them. Security fixes follow the private disclosure process in [SECURITY.md](SECURITY.md). +Every PR must close an existing issue, except automated dependency updates and the build and flaky-test fixes described below. In the PR's **Related Issue** section, use `Closes #NNN` for the issue covering that PR's scope. Split multi-PR work into a closable issue for each PR; a tracking issue can link them. Security fixes follow the private disclosure process in [SECURITY.md](SECURITY.md). Authors without write access to the target repository must link at least one issue with `state:accepted`, and every linked issue must be accepted. This applies to drafts and direct requests to agents. Authors with verified `WRITE`, `MAINTAIN`, or `ADMIN` access may create a PR without the acceptance label; they must still follow the issue-linking requirement above. PR body text, roadmap placement, other labels, and vouch status do not bypass acceptance. @@ -411,11 +411,13 @@ The `PR Issue Acceptance` workflow reports the native `OpenShell / PR Issue Acce Automated dependency update PRs, including Dependabot PRs, are exempt from the separate issue and closing-reference requirement. Human-authored dependency updates follow the normal issue requirement. The exception does not bypass `PR Issue Acceptance` for authors without repository write access or change applicable verification, review, or private vulnerability disclosure requirements. +Authors with `WRITE`, `MAINTAIN`, or `ADMIN` access may open a PR that only fixes a broken build or flaky tests without a separate issue. Describe the failure in the PR instead. Authors without write access follow the normal issue and acceptance requirements. + ### Branch Names Use `/-/` for contributor branches. Choose the Conventional Commit type that describes the work, such as `feat`, `fix`, `refactor`, `chore`, `perf`, `docs`, `test`, or `ci`. The description is a short lowercase slug separated by hyphens; the final component is your GitHub login, not initials. -For example, issue 1234 with contributor `octocat` uses `feat/1234-add-pagination/octocat`. Dependent PRs follow the same naming rule and branch from their parent PR's branch. +For example, issue 1234 with contributor `octocat` uses `feat/1234-add-pagination/octocat`. A PR without an issue omits the issue ID, such as `fix/flaky-sandbox-tests/octocat`. Dependent PRs follow the same naming rule and branch from their parent PR's branch. Branches created by automation, such as Dependabot and CI mirror branches, keep their generated names. For private security work, follow the authorized disclosure workflow and use a neutral description that does not expose vulnerability details.