diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 9adc12c..5fd4993 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -10,6 +10,26 @@ Closes # +## Demo Impact + + + +## Docs Impact + + + +## API Impact + + + +## CI Impact + + + +## Security Notes + + + ## Notes @@ -17,10 +37,12 @@ Closes # ## Checklist - [ ] Branch name follows `/--`. +- [ ] Branch category matches the issue's single primary category label. - [ ] Pull request is scoped to one issue, unless a documented multi-issue exception applies. - [ ] Pull request body explains what changed and how it was validated. - [ ] Relevant project checks pass. - [ ] Documentation is updated when behavior or user-facing commands change. +- [ ] Applicable impact sections required by `base_manifest.yaml` are complete, or explicitly say `None.` - [ ] Support/security claims link to the enforced matrix and caller responsibilities. - [ ] CHANGELOG is updated for notable user-visible or release-worthy changes. - [ ] Pull request includes `Fixes #` or `Closes #` when merge should close the issue. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1584a01..4db4599 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,17 +15,28 @@ operation must enter through the repository-owned `scripts/release` guard. ## Workflow -1. Create or choose a GitHub issue for roadmap or multi-step work. A small, - self-contained fix may be submitted directly from a public fork. -2. Use one of the standard issue labels: `bug`, `enhancement`, - `documentation`, `ci`, or `security`. -3. For tracked work, create an issue-backed branch: +1. Create or choose a GitHub issue before starting implementation work. + Contributions from a public fork are welcome, but the issue and + pull-request contract still applies. +2. Give the issue exactly one primary category label: + - `bug` for defects or regressions. + - `enhancement` for new capabilities, refactors, and maintenance. + - `documentation` for documentation-only work. + - `ci` for workflows, tests, release automation, or CI reliability. + - `security` for security hardening, dependency pinning, or vulnerabilities. +3. If the issue is tracked in the repository Project, move it to `In Progress` + before branch or worktree work begins. Move it to `In Review` when the pull + request opens, and verify it is `Done` after merge or closure. +4. Create an issue-backed branch: ```text /-- ``` -4. Use a dedicated Git worktree for each pull request so the main checkout can + The category must match the issue's one primary category label, and the date + must be a real calendar date. The branch-name ruleset and the trusted + `base/issue-branch-policy` workflow enforce this for every contribution. +5. Use a dedicated Git worktree for each pull request so the main checkout can stay on the default branch: ```bash @@ -33,12 +44,16 @@ operation must enter through the repository-owned `scripts/release` guard. git worktree add -b ../base-bash-libs-worktrees/ origin/ ``` -5. Keep the pull request scoped to the issue when one exists and link it with - `Fixes #` or `Closes #` when merge should close the issue. -6. Run the project checks before opening or updating a pull request. -7. Update `CHANGELOG.md` only for notable user-visible or release-worthy +6. Keep the pull request scoped to one issue and link it with `Fixes #` + or `Closes #` when merge should close the issue. Fill in the standard + `Summary`, `Issue`, and `Validation` sections plus any applicable impact + sections required by `base_manifest.yaml`. +7. Run the project checks before opening or updating a pull request. The full + hosted tests and quality workflows remain release gates even though the + default branch baseline does not require every job as a merge check. +8. Update `CHANGELOG.md` only for notable user-visible or release-worthy changes. -8. After merge, sync the default branch, remove the worktree, and delete merged +9. After merge, sync the default branch, remove the worktree, and delete merged local and remote branches when safe: ```bash diff --git a/base_manifest.yaml b/base_manifest.yaml index 8fe1cd4..adcd111 100644 --- a/base_manifest.yaml +++ b/base_manifest.yaml @@ -19,4 +19,24 @@ release: formula_path: Formula/base-bash-libs.rb package: basefoundry/base/base-bash-libs +github: + pr: + required_sections: + default: + - Summary + - Issue + - Validation + labels: + needs-demo: + - Demo Impact + security: + - Security Notes + paths: + docs/**: + - Docs Impact + lib/bash/**: + - API Impact + .github/**: + - CI Impact + artifacts: [] diff --git a/docs/ci-policy.md b/docs/ci-policy.md index 75b85ea..8b0bf28 100644 --- a/docs/ci-policy.md +++ b/docs/ci-policy.md @@ -11,34 +11,38 @@ latest commit on `main`). This prevents new formatting debt while allowing the existing v1-to-v2 codebase to be cleaned incrementally; touching a legacy file puts its complete contents under the formatter gate. -## Required checks +## Default-branch baseline -The `main` branch must require these checks before merge: +`base-bash-libs` follows the same modest default-branch baseline as Base: -- `Tests / Validate (macos-14)` -- `Tests / Validate (ubuntu-24.04)` -- `Tests / Compatibility (Bash 4.4.23)` -- `Tests / Compatibility (Bash 5.0.18)` -- `Tests / Compatibility (Bash 5.2.37)` -- `Tests / Compatibility smoke (Bash 4.2.53)` -- `Tests / Release gates (matrix and provenance)` -- `Quality / Quality gates` -- `Issue Branch Policy / Publish issue branch policy` +- pull requests are required and merges are squash-only; +- the `Base branch naming` ruleset protects non-default branches; +- the `Base default branch protection` ruleset requires the trusted + `base/issue-branch-policy` status, and prevents deletion and non-fast-forward + updates; +- administrators remain subject to branch protection; and +- no approval count or individual Tests/Quality job is a default merge + requirement. -Require one approving review, dismiss stale approvals after new commits, and -require branches to be up to date before merging. Administrators should keep -the protection enforced; an emergency merge is an auditable exception, not a -replacement for the required checks. +This is a merge-policy choice, not a validation waiver. The `Tests` and +`Quality` workflows still run on pull requests and `main`, and they remain +release gates. Run the complete local validation and release readiness checks +before publishing a release, even when a pull request can merge after the +issue-branch policy succeeds. + +The live classic branch-protection rule keeps strict status-check behavior for +any checks configured in the future, but the repository's required merge +contexts are intentionally supplied by the Base-managed ruleset above. ## Emergency procedure -1. Record the incident, affected commit, approver, and reason in the pull - request and the umbrella issue. +1. Record the incident, affected commit, and reason in the pull request and + the umbrella issue. 2. Use an administrator-only bypass only for a time-sensitive remediation. 3. Restore branch protection immediately and run the complete workflows on the resulting `main` commit. -4. Open a follow-up issue for every skipped check or review, with a concrete - owner and due date. +4. Open a follow-up issue for every skipped policy or validation step, with a + concrete owner and due date. ## Platform claims diff --git a/docs/community.md b/docs/community.md index b391d5c..b39825d 100644 --- a/docs/community.md +++ b/docs/community.md @@ -10,9 +10,10 @@ vulnerabilities or sensitive conduct concerns. Normal contributions may come from a public fork and may be submitted with -standard Git, GitHub, Bats, and ShellCheck tooling. `basectl`, dedicated -worktrees, and a pre-existing issue are helpful but not prerequisites for a -small fix. Required CI and the review checklist remain mandatory. +standard Git, GitHub, Bats, and ShellCheck tooling. A pre-existing issue, +dedicated worktree, and Base helper command are the recommended workflow for +tracked work; the issue, validation, and review-checklist requirements still +apply to small fixes. ## Review and decisions