diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..8e12c4e --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,49 @@ +# Contributing: staged delivery + +The normal change path for this repository is **`feature/* → staging → main`**. + +1. Create a short-lived feature or fix branch from `staging` and open a reviewed + pull request back to `staging`. This includes maintenance, dependency updates, + documentation, and agent-authored changes. +2. Run the repository's required CI and validate the integrated candidate in its + lower environment. Record the commit/artifact and smoke or acceptance results. + For libraries and documentation, record the applicable package/test/build + evidence; a branch name does not establish that a deployed environment exists. +3. Open a separate promotion PR from `staging` to `main` in this repository. + Link the validated candidate, required human approvals, release checklist and + rollback plan. A release includes every change in that candidate; unfinished + work must stay out or be safely disabled. +4. Use the existing deployment procedure and verify the running version and + relevant user-visible behavior. Branch merges alone do not prove deployment. + +Do not direct-push normal work to `staging` or `main`, or open a feature PR +straight into `main`. An emergency exception requires the approved incident +process, explicit authorization, exact revision, validation and recovery evidence, +and subsequent reconciliation into `staging`. A label or a branch called +`hotfix` does not grant an exception. + +When this guide is inherited by another repository, use that repository’s +explicitly documented `staging` or `qa` integration branch and its existing +production branch (`main`, or a documented legacy name). Local lane mappings +take precedence over this repository’s branch names, not over staged review. + +## Enforcement and rollout + +Where installed, the PR routing workflow checks branch and repository identity. It does not +verify application tests, approvals, deployed artifacts, or emergency authority. +A check is mandatory only when GitHub branch protection/rulesets require it. +Protect both integration and release branches with reviewed PRs, prohibit force +pushes/deletions, and preserve all existing stronger checks. Require the routing +check on release branches after the workflow is installed and has run there; +do not require a check that is not yet available. Review automation that writes +directly to protected branches before enabling restrictions, and route its +changes through PRs. Keep emergency bypass access narrow and audited. + +Before promotion, reconcile any existing topic PRs aimed at production. Inspect +their diff against the integration branch before retargeting: changing a PR base +can change its contents. Do not bulk merge or retarget other contributors' PRs. + +The organization standard is documented in the +[staged delivery guide](https://github.com/GapIntelligence/.github-private/blob/staging/docs/practices/staged-github-flow.md). +New contributors should walk through their first integration PR and a release +example with the repository owner; this file is not a training acknowledgment. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..1dacbed --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +# Summary + +Describe the problem and resulting behavior. + +# Validation + +Record checks run, results, and any limitations. + +## Staged delivery + +- [ ] Feature/fix/maintenance PR targets `staging`. +- [ ] If this is a promotion to `main`, its source is `staging` in this repository. +- [ ] Validation evidence identifies the candidate revision/artifact and relevant environment. +- [ ] Promotion has the required human approvals, release checklist and rollback plan. + +For an authorized emergency exception, link the incident, approver, validation +and reconciliation plan. A checked box or label does not grant an exception. diff --git a/.github/workflows/staged-flow.yml b/.github/workflows/staged-flow.yml new file mode 100644 index 0000000..50a32ec --- /dev/null +++ b/.github/workflows/staged-flow.yml @@ -0,0 +1,43 @@ +name: Staged Flow + +on: + pull_request: + branches: ["staging", "main"] + types: [opened, synchronize, reopened, edited, ready_for_review] + +permissions: {} + +jobs: + route: + runs-on: ubuntu-latest + timeout-minutes: 2 + steps: + - name: Verify staged PR route + env: + INTEGRATION_BRANCH: staging + RELEASE_BRANCH: main + FINAL_RELEASE_BRANCH: "" + shell: bash + run: | + python3 - <<'PYTHON' + import json + import os + from pathlib import Path + + pr = json.loads(Path(os.environ["GITHUB_EVENT_PATH"]).read_text())["pull_request"] + base = pr["base"]["ref"] + head = pr["head"]["ref"] + head_repo = (pr["head"].get("repo") or {}).get("full_name") + base_repo = pr["base"]["repo"]["full_name"] + integration = os.environ["INTEGRATION_BRANCH"] + release = os.environ["RELEASE_BRANCH"] + tail = os.environ.get("FINAL_RELEASE_BRANCH", "") + + if base == integration: + print("Integration PR: complete the repository's required checks and review.") + else: + expected = integration if base == release else release if tail and base == tail else None + if expected is None or head != expected or head_repo != base_repo: + raise SystemExit("Invalid release route: promote the integration branch from this repository; feature and fork PRs belong in staging/QA.") + print("Promotion route verified. CI, lower-environment evidence and release authorization remain required.") + PYTHON diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..1424ac2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,5 @@ +Normal change flow: feature/fix branch -> staging -> main. +Open feature, maintenance, dependency and agent PRs against staging; use a separate staging -> main promotion PR. +Do not direct-push to integration or release branches or bypass lower-environment validation. +Emergency exceptions require explicit authorization, evidence and reconciliation into staging. +Read .github/CONTRIBUTING.md for the repository lane, review, validation and release requirements. diff --git a/README.md b/README.md index f6ceaaf..0c5b4fe 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,6 @@ +> **Contribution flow:** `feature/* → staging → main`. Open normal PRs against `staging`. +> See the [contribution and release guide](.github/CONTRIBUTING.md). + # OpenBrand ![CI](https://github.com/GapIntelligence/.github/actions/workflows/ci.yml/badge.svg)