diff --git a/CHANGELOG.md b/CHANGELOG.md index b8213f0..5f79ff6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -14,6 +14,10 @@ and versions are tracked in the repo-root `VERSION` file. ### Changed - Include `uv.lock` freshness in the authoritative local validation aggregate (#424). +- Document maintainer, independent review, release continuity, and reviewer + onboarding responsibilities for the 1.0 release gate (#252). +- State the explicit 0.3.x security-support row and make the v1.0 schedule + evidence-driven rather than asserting an untracked ship date. - Add CodeQL analysis, Dependabot update policy, and repository security-control documentation for the 1.0 release gate (#280). - Configure Dependabot for the repository's checked-in uv lockfile instead of diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 385b90d..8a09ffb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,8 @@ Thank you for improving this project. Please read the [Code of Conduct](CODE_OF_CONDUCT.md) before participating. +Project roles, review expectations, and release continuity are documented in +[`GOVERNANCE.md`](GOVERNANCE.md). ## Development setup diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..cc71cc4 --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,87 @@ +# Project governance + +This document describes how `base-cli` makes API, compatibility, security, and +release decisions. It is deliberately lightweight: the project is maintained +in the open through issues, pull requests, required checks, and dated release +artifacts. + +## Current responsibilities + +| Role | GitHub identity | Responsibility | +| --- | --- | --- | +| Project maintainer | [`codeforester`](https://github.com/codeforester) | Roadmap, issue triage, merge decisions, release preparation, and continuity planning | +| Independent release/security reviewer | [`rameshulugar`](https://github.com/rameshulugar) | Review protected release and security-source changes independently of the last pusher | + +The maintainer is accountable for keeping this table current. A role is not a +claim that a person has reviewed a particular change; the pull request and +release records remain authoritative. + +## Review and decision rules + +- Every implementation starts from a GitHub issue with a stated scope and + acceptance criteria. +- A pull request must identify the issue, describe compatibility impact, and + report the authoritative validation gates. +- Public API, JSON schema, command-protocol, dependency-window, security, and + release-workflow changes require explicit documentation and regression + evidence in the same change train. +- The last pusher must not be the sole reviewer for a protected release. +- A disagreement is recorded in the issue or pull-request thread; the + maintainer records the final decision and its rationale in the changelog or + relevant contract document. +- Security reports follow `SECURITY.md` and are never disclosed through a + public implementation issue before coordinated remediation. + +## Release ownership and continuity + +The release owner prepares the version/changelog change, candidate artifact, +TestPyPI rehearsal, downstream wheel validation, and release evidence. The +independent reviewer checks the exact commit, required gates, artifact +checksums, SBOM/provenance attestations, and PyPI/GitHub metadata before the +protected environment is approved. + +If the maintainer is unavailable, the independent reviewer may coordinate an +already-approved release or security response, but may not silently change the +public API or bypass required checks. A temporary exception must be time-bound, +name an owner and expiry, and be recorded in the relevant issue. + +## Reviewer onboarding checklist + +An additional reviewer is considered trained after completing and recording: + +1. a clean checkout and `./tests/full_validate.sh` run; +2. the public API, JSON-contract, compatibility, and security review guides; +3. a TestPyPI candidate install and downstream consumer smoke test; +4. checksum, SBOM, provenance, and attestation verification for a release + artifact; and +5. a supervised review of one release-source or security pull request. + +The training record belongs in the linked governance issue or release checklist +and must not be inferred solely from repository write access. + +## Project health + +Maintainers review these indicators at least once per release cycle: + +- open P1 issues and their dependency graph; +- time to first response and time to review for pull requests; +- green required checks on the default branch; +- release-candidate and downstream-consumer evidence; +- security-alert age and remediation status; and +- independent adopter pilots and permissioned outcomes. + +The current `v1.0.0` plan targets a stable core release after the documented +release-candidate, downstream, and independent-review evidence is complete; +the milestone and linked issues are the source of truth for scheduling. The +broader language-neutral platform and catalog work remains explicitly deferred +unless a separate roadmap decision brings it into scope. + +## Becoming a maintainer + +Regular contributors can be nominated through a public issue after they have +demonstrated sustained, high-quality reviews and familiarity with the full +validation and release gates. The maintainer records the nomination, conflict +disclosures, granted repository permissions, and a succession handoff plan. + +See [`CONTRIBUTING.md`](CONTRIBUTING.md), [`SECURITY.md`](SECURITY.md), and +[`docs/releasing.md`](docs/releasing.md) for the operational procedures. diff --git a/SECURITY.md b/SECURITY.md index aa07523..53483fe 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -28,14 +28,15 @@ repository maintainers through the private contact route shown on the ## Supported versions Security fixes are targeted at the latest released minor line and the current -development branch. At the time this policy was published, that means the -`0.4.x` release line and `main`. Older pre-1.0 lines are best effort only; +development branch. At the time this policy was updated, that means the +`0.5.x` release line and `main`. Older pre-1.0 lines are best effort only; upgrade to the latest release before requesting a backport. A release that changes the supported window will update this table and the changelog. | Version | Security support | | --- | --- | -| `0.4.x` | Supported | +| `0.5.x` | Supported | +| `0.4.x` | Upgrade strongly recommended; best effort only | | `0.3.x` | Upgrade strongly recommended; best effort only | | `main` | Supported for fixes merged before the next release | | `<0.3` | Upgrade strongly recommended; best effort only | diff --git a/docs/index.md b/docs/index.md index 0dd2c18..f93108e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -64,6 +64,10 @@ application. for dated CI results and the permissioned-adopter program. - Read [API stability](api-stability.md) and the [migration guide](migrations.md) before upgrading across a compatibility boundary. +- Review the project's [governance and maintainer responsibilities](https://github.com/basefoundry/base-cli/blob/main/GOVERNANCE.md) + before taking on release or security work. +- Start new applications with the small `base_cli.core` surface and consult the + [API manifest](api-manifest.json) for advanced and integration tiers. - Start new applications with the small `base_cli.core` surface and consult the [API manifest](api-manifest.json) for advanced and integration tiers. - Browse the [complete public API reference](api-reference.md) for exported diff --git a/docs/releasing.md b/docs/releasing.md index 5d4e4d2..52b40b6 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -208,11 +208,12 @@ publishing for this repository and workflow before the dispatch can upload. The `pypi` GitHub environment requires approval, rejects self-review, disallows administrator bypass, and is configured with the PyPI trusted publisher for `.github/workflows/package.yml`. No long-lived PyPI token is stored in the -repository. Production publication therefore waits for an independent -reviewer until maintainer-capacity work in [#252](https://github.com/basefoundry/base-cli/issues/252) -adds one. If a temporary solo-maintainer exception is ever needed, it must be -time-bounded and record an owner, expiry, audit trail, and link to #252 before -an administrator changes the environment policy. +repository. The independent release/security reviewer is designated in +[`GOVERNANCE.md`](https://github.com/basefoundry/base-cli/blob/main/GOVERNANCE.md); the release record must identify the +reviewer who checked the exact artifact and commit. If a temporary solo- +maintainer exception is ever needed, it must be time-bounded and record an +owner, expiry, audit trail, and link to [#252](https://github.com/basefoundry/base-cli/issues/252) +before an administrator changes the environment policy. ## Recovery