mirror of
https://github.com/pewdiepie-archdaemon/odysseus.git
synced 2026-10-20 22:02:20 +02:00
Merge pull request #6736 from alteixeira20/docs/maintainer-handbook-governance-v1
docs(maintainers): add public governance handbook and review playbook
This commit is contained in:
Alexandre Teixeira
+5
-1
@@ -7,7 +7,7 @@ Thanks for helping. The project is moving quickly, so the best contributions are
|
||||
Odysseus has two branches:
|
||||
|
||||
- **`dev`** — where all PRs land. Things can be in flux here; the merge button gets used freely.
|
||||
- **`main`** — what users run. Curated and tested by the maintainer. Fast-forwarded to a stable `dev` commit at each release.
|
||||
- **`main`** — what users run. Curated and tested by the release's [Release Maintainer](docs/maintainers/testing-and-releases.md#release-ownership). Fast-forwarded to a stable `dev` commit at each release.
|
||||
|
||||
**Open your PR against `dev`, not `main`.** The GitHub "base" dropdown defaults to `dev`. If you opened a PR against `main` by accident, click "Edit" on the PR and change the base — no rebase needed.
|
||||
|
||||
@@ -62,6 +62,10 @@ docker compose logs --tail=120 odysseus
|
||||
|
||||
Mention what you ran in the pull request description. If you could not run a check, say so.
|
||||
|
||||
## Maintainer governance and review guidance
|
||||
|
||||
For repository roles, product decisions, risk-based approvals, issue triage, independent security reviews, CodeQL findings, and release handoffs, see the [Odysseus maintainer handbook](docs/maintainers/README.md). This complements the contributor requirements below and does not change the branch model or current PR template.
|
||||
|
||||
## Pull Requests
|
||||
|
||||
Good pull requests usually include:
|
||||
|
||||
@@ -0,0 +1,38 @@
|
||||
# Odysseus maintainer handbook
|
||||
|
||||
Odysseus maintainers are trusted to act, not to wait for permission. The default is individual responsibility; additional review is required when the **risk** warrants it.
|
||||
|
||||
This handbook records the project's maintainer governance and gives reviewers a reusable process. It complements [CONTRIBUTING.md](../../CONTRIBUTING.md) and [SECURITY.md](../../SECURITY.md); it does not replace the PR template, repository protections, or product decisions.
|
||||
|
||||
## At a glance
|
||||
|
||||
| Area | Working rule |
|
||||
|---|---|
|
||||
| Product direction | Pewds is the Product Owner |
|
||||
| Ordinary, reversible maintainer PR | Self-merge allowed after appropriate validation and applicable repository checks |
|
||||
| External contribution | Maintainer review required |
|
||||
| High-risk change | At least one **independent, qualified** maintainer review |
|
||||
| Access | Need-to-have, least privilege, separately granted per system |
|
||||
| Release | A designated Release Maintainer owns preparation and publish |
|
||||
| Inactivity | Access review after 2 months without activity, notice, or response |
|
||||
| Documentation | Repository Markdown is canonical |
|
||||
|
||||
These are governance rules, not guarantees that a GitHub permission or branch-protection setting permits a particular action. Respect the stronger applicable automated gate.
|
||||
|
||||
## Start here
|
||||
|
||||
- [Roles and access](roles-and-access.md): responsibility, permissions, and continuity.
|
||||
- [Product and feature proposals](product-and-features.md): product approval versus technical ownership.
|
||||
- [Changes and review](changes-and-review.md): review thresholds, self-merge, contributor corrections.
|
||||
- [Practical review playbook](review-playbook.md): risk, provenance, CI, CodeQL, independent audit, and handoff evidence.
|
||||
- [Triage](triage.md): turning incoming reports into actionable work.
|
||||
- [Testing and releases](testing-and-releases.md): evidence, platform validation, promotion to main.
|
||||
- [Documentation](documentation.md): canonical sources, updates, and traceability.
|
||||
|
||||
## Accountability
|
||||
|
||||
Maintainers own the changes they take on, including validation, regression prevention, follow-up, and rollback when needed. Roles describe responsibilities, not a hierarchy of technical approval.
|
||||
|
||||
Important product-direction decisions go through the Product Owner. Maintainers retain responsibility for feasibility, implementation, maintainability, and security.
|
||||
|
||||
AI coding or review agents can help collect evidence, test hypotheses, and prepare changes, but they are not the qualified human reviewer required for high-risk changes. A maintainer must inspect and accept the evidence.
|
||||
@@ -0,0 +1,62 @@
|
||||
# Changes and review
|
||||
|
||||
Review is **risk-based**. Trusted maintainers should be able to ship ordinary work without creating a queue of ceremonial approvals.
|
||||
|
||||
## Required review
|
||||
|
||||
| Change | Minimum review rule |
|
||||
|---|---|
|
||||
| Ordinary, reversible maintainer change | Independent approval optional; self-merge permitted after appropriate validation |
|
||||
| External contribution | Maintainer review required |
|
||||
| High-risk change | At least one independent, qualified maintainer review required |
|
||||
|
||||
Repository branch protection and required checks also apply. Never treat this document as permission to bypass a live protection rule.
|
||||
|
||||
## Ordinary maintainer changes
|
||||
|
||||
1. Open a PR against `dev`, scoped to one coherent change.
|
||||
2. Explain intent, expected behavior, validation, and rollback if relevant.
|
||||
3. Run suitable tests and inspect the actual result.
|
||||
4. Ensure applicable required checks pass, address feedback, and merge when ready.
|
||||
|
||||
Self-merge is allowed for ordinary reversible work. The author remains responsible for follow-up, correction, and rollback.
|
||||
|
||||
## External contributions and small corrections
|
||||
|
||||
External contributions receive maintainer review.
|
||||
|
||||
A maintainer may directly fix a **small, obvious** problem in a contributor PR when the intended behavior is clear and the repair is faster than a separate round trip. Document what changed, preserve contributor attribution and history, avoid force-pushing, and re-run affected checks.
|
||||
|
||||
Substantive or ambiguous corrections require discussion with the contributor or a separately scoped correction. A maintainer must not silently turn a contributor's PR into unrelated work. Any corrective commit changes the SHA being reviewed; update validation and audit evidence accordingly.
|
||||
|
||||
## High-risk changes
|
||||
|
||||
High-risk work requires **at least one independent qualified review**. The author cannot be the only approver. Examples:
|
||||
|
||||
- Authentication, authorization, tenancy, sandboxing, agent tool permissions, or secrets.
|
||||
- Outbound network and SSRF defenses, sensitive integrations, and deployment access.
|
||||
- Destructive operations, deletion, filesystem ownership, and data migrations.
|
||||
- Persistence and concurrency invariants with possible data loss.
|
||||
- Major architectural contracts, release infrastructure, or changes hard to roll back.
|
||||
|
||||
A high-risk review should verify the threat or failure model, exact final commit, reproducer or regression evidence, failure and rollback behavior, and the relevant CI/security findings. Use the [review playbook](review-playbook.md).
|
||||
|
||||
## Cross-area changes and CODEOWNERS
|
||||
|
||||
Touching multiple areas does **not** automatically require multiple approvals. Consult domain expertise when needed. `.github/CODEOWNERS` currently contains no ownership rules; the per-area map is under discussion in [issue #593](https://github.com/odysseus-dev/odysseus/issues/593). Once populated, it helps identify reviewers and accountable contacts; it is not a blanket approval requirement by itself.
|
||||
|
||||
## Validation and UI evidence
|
||||
|
||||
Automated tests count as runtime evidence when they truly exercise the changed behavior. Use manual validation when coverage is insufficient.
|
||||
|
||||
For any change to visible UI behavior, follow the current [contributor UI checklist](../../CONTRIBUTING.md#style-and-visual-changes) and the repository PR template. Screenshots or clips are expected when they materially demonstrate the rendered result; screenshots alone do not replace behavioral tests.
|
||||
|
||||
## Disagreement and escalation
|
||||
|
||||
The maintainer doing the work owns ordinary implementation decisions within approved product direction and existing technical contracts. For substantive disagreements:
|
||||
|
||||
1. Involve a qualified maintainer with relevant expertise.
|
||||
2. Escalate unresolved cross-cutting technical issues to trusted project-wide maintainers.
|
||||
3. Refer product-direction disagreements to the Product Owner.
|
||||
|
||||
Security findings should be handled via [SECURITY.md](../../SECURITY.md), without disclosing exploit details in public issues. Repository protection rules should support these risk-based policies and should not accidentally force independent approval for every ordinary maintainer PR.
|
||||
@@ -0,0 +1,32 @@
|
||||
# Documentation
|
||||
|
||||
Repository Markdown is the canonical source for project documentation. A public docs site may be generated from it; avoid maintaining an independent wiki copy unless there is a deliberate future decision to do so.
|
||||
|
||||
## Where information belongs
|
||||
|
||||
| Location | Purpose |
|
||||
|---|---|
|
||||
| `/design` | Product intent, proposals, and accepted decisions (when those paths are used) |
|
||||
| `/specs` | Technical contracts and invariants |
|
||||
| `/website` | User, setup, configuration, and deployment guidance (published as the docs site) |
|
||||
| `/docs` | Developer, architecture, security, and maintainer guidance |
|
||||
| Root Markdown | Discoverable entry points and policies |
|
||||
|
||||
Keep root documents easy to find:
|
||||
|
||||
- `README.md`
|
||||
- `CONTRIBUTING.md`
|
||||
- `SECURITY.md`
|
||||
- `THREAT_MODEL.md`
|
||||
|
||||
Not every named directory exists today; do not invent a parallel documentation store just to match this map.
|
||||
|
||||
## Updating documentation
|
||||
|
||||
When behavior, architecture, a workflow, or its verification requirements change, update the canonical documentation in the same PR when appropriate.
|
||||
|
||||
Separate **policy** from **examples**: examples may evolve with tooling; changes to role authority, review requirements, or product ownership require an explicit governance decision. Do not introduce a new mandatory approval rule through a checklist alone.
|
||||
|
||||
Documentation PRs should link the relevant issue, record what was reviewed (links, commands, or affected features), and avoid publishing private channels, account names, local paths, secrets, or confidential incident details.
|
||||
|
||||
For practical examples of review evidence, see the [review playbook](review-playbook.md). For contributor setup and PR requirements, use [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
@@ -0,0 +1,48 @@
|
||||
# Product and feature proposals
|
||||
|
||||
Pewds ([@pewdiepie-archdaemon](https://github.com/pewdiepie-archdaemon)) is the Product Owner for Odysseus and has final authority over product direction. Maintainers own technical feasibility, implementation, and safety.
|
||||
|
||||
## Which changes require product approval?
|
||||
|
||||
**Product Owner approval before implementation:** substantial new features, changes to product direction, and product changes that are hard to reverse.
|
||||
|
||||
**No separate product approval by default:** bug fixes, security fixes, maintenance, tests, CI, documentation, internal refactors, and small, reversible product changes within existing direction.
|
||||
|
||||
Maintainers may make those smaller product decisions. Pewds can ask for changes or a rollback; the maintainer owns safe rollback or recovery.
|
||||
|
||||
### Urgent security and reliability fixes
|
||||
|
||||
Urgent fixes or containment may proceed without prior product approval, even if behavior temporarily changes. Keep the change to what stops the immediate problem, notify Pewds promptly, and record the reason and rollback or recovery plan. Agree on any lasting product-direction change with Pewds afterwards. Normal high-risk review and repository checks still apply.
|
||||
|
||||
## Product Owner initiated
|
||||
|
||||
```text
|
||||
Product Owner proposal or implementation
|
||||
-> technical feasibility
|
||||
-> plan and implementation
|
||||
-> risk-based review and validation
|
||||
```
|
||||
|
||||
A Product Owner proposal is already product-approved; it is not automatically technically approved or exempt from high-risk review.
|
||||
|
||||
## Community or maintainer initiated
|
||||
|
||||
Community proposals start as a Feature Request issue. Check [ROADMAP.md](../../ROADMAP.md) and existing issues first; take early ideas to [Discussions](https://github.com/odysseus-dev/odysseus/discussions/categories/ideas).
|
||||
|
||||
```text
|
||||
Feature proposal
|
||||
-> Product Owner accepts / rejects, where approval is required
|
||||
-> technical feasibility
|
||||
-> plan and implementation
|
||||
-> risk-based review and validation
|
||||
```
|
||||
|
||||
Record the decision in an issue, proposal, work item, or PR so future maintainers can discover it. Do not rely on a chat-only decision.
|
||||
|
||||
## Decision boundaries
|
||||
|
||||
The Product Owner decides **what belongs in Odysseus**. Maintainers decide **how approved work is built safely and maintainably**.
|
||||
|
||||
A rejected or out-of-scope feature can be maintained independently in a contributor's fork.
|
||||
|
||||
If the Product Owner is unavailable, work requiring prior product approval waits unless authority was explicitly delegated. Smaller decisions and urgent fixes follow the rules above.
|
||||
@@ -0,0 +1,129 @@
|
||||
# Practical PR review playbook
|
||||
|
||||
Use this as a **repeatable review method**, not as an extra organizational approval ladder. The binding minimums remain in [changes and review](changes-and-review.md): ordinary maintainer changes may be self-merged, external PRs require maintainer review, and high-risk work requires at least one independent qualified maintainer review.
|
||||
|
||||
No single checklist replaces engineering judgment. Increase depth with risk.
|
||||
|
||||
## 1. Understand the PR and establish its review gates
|
||||
|
||||
- Establish the problem, what the PR fundamentally proposes, and why the approach makes sense.
|
||||
- Check product direction, architecture fit, and scope before detailed review.
|
||||
- Write down the questions the review must answer, the evidence needed, and what would block further review or approval.
|
||||
- Confirm repository, source fork, target branch (`dev`), exact **HEAD SHA**, and current base.
|
||||
- Review the full effective diff, commit history, issue, prior feedback, and related upstream changes.
|
||||
- Confirm the branch is mergeable against the **current** `dev`, not an older local snapshot.
|
||||
- Identify the user-facing contract, affected data and users, security boundaries, and rollback plan.
|
||||
- Separate pre-existing upstream problems from regressions introduced or made reachable by the PR.
|
||||
|
||||
Example read-only commands:
|
||||
|
||||
```bash
|
||||
REPO="odysseus-dev/odysseus"
|
||||
PR=1234
|
||||
gh pr view "$PR" --repo "$REPO" --json title,state,isDraft,headRefOid,baseRefName,mergeable
|
||||
gh pr diff "$PR" --repo "$REPO"
|
||||
gh pr checks "$PR" --repo "$REPO"
|
||||
```
|
||||
|
||||
A green check on an old commit does not verify the revised branch.
|
||||
|
||||
## 2. Review the failure and threat model
|
||||
|
||||
For the relevant change, ask what happens with malformed input, missing auth state, wrong owner, concurrent requests, stale caches, partial failure, retries, cancelled jobs, unavailable dependencies, and restart/recovery.
|
||||
|
||||
Prioritize boundaries that can lose data or authority: identity, delegated API tokens, filesystem confinement, email deletion, persistence versioning, network/SSRF destinations, secrets, and agent tool execution.
|
||||
|
||||
For security claims, demonstrate the source-to-sink path and the *actual* guard. Tests must represent production middleware or transport where a unit mock could conceal a bypass.
|
||||
|
||||
## 3. Correct without obscuring contributor work
|
||||
|
||||
For small, unambiguous issues, maintainers may add focused corrections directly to a contributor PR under [the contribution review policy](changes-and-review.md#external-contributions-and-small-corrections). Preserve provenance, explain the change, prefer normal commits and fast-forward pushes, and avoid unrelated rewrites.
|
||||
|
||||
For substantive or ambiguous work, ask the contributor or prepare a clearly separated patch. Any code change means validating **the new SHA**, not approving based solely on the previous audit.
|
||||
|
||||
## 4. Build an evidence record
|
||||
|
||||
Run contributor code under the [runtime isolation rules](testing-and-releases.md#runtime-isolation).
|
||||
|
||||
Useful evidence includes:
|
||||
|
||||
- Pre-fix reproduction, expected outcome, and actual outcome.
|
||||
- Focused regression tests for the fix and broad suites relevant to cross-cutting effects.
|
||||
- Actual runtime checks (browser/UI, backend, Docker, supported OS) where necessary.
|
||||
- Exact executed commands, result counts, skipped cases, and environmental limitations.
|
||||
- GitHub required checks and conflict-free state on the exact final SHA.
|
||||
- Relevant operational consequences (data migration, rollback, compatibility).
|
||||
|
||||
Keep audits reproducible. A screenshot alone is not a functional test, and a passing mocked test is not proof that a production integration path is safe.
|
||||
|
||||
## 5. Independent review for high-risk changes
|
||||
|
||||
A separate **qualified maintainer** must inspect high-risk changes; the implementing author cannot be the sole reviewer. Independent coding agents may be useful for adversarial tests and cross-checks, but **an AI agent is not itself a GitHub approver** and does not replace human accountability.
|
||||
|
||||
To avoid confirmation bias, give the independent reviewer the current SHA, changed files, acceptance criteria, known reproduction, and explicit permission to challenge the proposed solution. Preserve unresolved findings and require a new audit when meaningful fixes change the diff.
|
||||
|
||||
## CodeQL and security scanning
|
||||
|
||||
A successful CodeQL workflow means analysis ran, not that the security dashboard is empty. Likewise, resolving a PR discussion does not necessarily resolve its code-scanning alert.
|
||||
|
||||
For each relevant alert:
|
||||
|
||||
1. Record the alert number, rule, severity, file/line, state, and source-to-sink trace if applicable.
|
||||
2. Compare with the current `dev` baseline; decide whether the PR introduced, exposed, or did not affect it.
|
||||
3. Reproduce or reason through the actual production behavior, including validation and authorization.
|
||||
4. **Fix** credible vulnerabilities, preferably with a regression test. Do not hide them by broad suppressions.
|
||||
5. **Recommend dismissal** only for a demonstrable false positive or a stale/invalid finding, with a precise technical explanation; only authorized maintainers should dismiss alerts.
|
||||
6. Document genuine but intentionally accepted risk separately. A true positive is not a false positive merely because it is deliberate.
|
||||
7. Rerun or inspect updated analysis on the final commit and confirm no blocking issues remain.
|
||||
|
||||
Never publish exploit payloads, secrets, or credentials in public review comments. See [SECURITY.md](../../SECURITY.md).
|
||||
|
||||
## 6. Decide and integrate
|
||||
|
||||
Before approval or self-merge, verify:
|
||||
|
||||
- Current branch and reviewed SHA are still the ones to be merged.
|
||||
- All applicable required checks are complete and successful.
|
||||
- High-risk independent review is present, where required.
|
||||
- No unresolved, credible P0/P1/P2 security or data-integrity defects remain in the change. Resolve or explicitly document P3 observations with a tracked owner and priority.
|
||||
- Review discussions, compatibility risks, and operational handoffs have been addressed.
|
||||
- The correct target is `dev`; `main` is curated for releases.
|
||||
|
||||
This P0-P3 classification is [triage guidance](triage.md#practical-priority-language), not a replacement for branch protection or an excuse to self-approve high-risk work. Maintainers may apply a stricter bar where warranted.
|
||||
|
||||
For a final manual merge, GitHub CLI supports an exact-head guard:
|
||||
|
||||
```bash
|
||||
gh pr merge 1234 --repo odysseus-dev/odysseus --squash \
|
||||
--match-head-commit <reviewed-full-head-sha>
|
||||
```
|
||||
|
||||
Use `--delete-branch` only when removing the source branch is appropriate and does not disrupt another workstream. Do not force a merge past review or security requirements.
|
||||
|
||||
## 7. Post-merge follow-up
|
||||
|
||||
Verify the PR actually merged and reference its integration commit. Record remaining operational work, such as schema migrations, backup/restore verification, service restarts, or compatibility documentation. A code change to a container mount does **not** by itself migrate existing runtime data.
|
||||
|
||||
Do not silently mark a deferred data migration complete; track its owner, evidence, rollback, and execution separately.
|
||||
|
||||
## Reusable reviewer handoff
|
||||
|
||||
```text
|
||||
PR / target:
|
||||
Reviewed source HEAD SHA:
|
||||
Current target branch SHA:
|
||||
Scope and changed files:
|
||||
Impact and risk classification:
|
||||
Security / correctness invariants challenged:
|
||||
Pre-fix reproducer and post-fix evidence:
|
||||
Tests run, skipped, and environment:
|
||||
CodeQL / scanning alert dispositions:
|
||||
Required GitHub checks (exact SHA):
|
||||
Mergeability and remaining conflicts:
|
||||
Unresolved P0 / P1 / P2 / P3 findings:
|
||||
Rollback / operational follow-ups:
|
||||
Independent qualified review required? Completed?
|
||||
Verdict: APPROVED / CHANGES REQUIRED / BLOCKED
|
||||
```
|
||||
|
||||
State what was actually verified. Do not write "all checks green" if only a subset of workflows was inspected.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Roles and access
|
||||
|
||||
Roles clarify who is accountable. They do not create a management chain or automatically grant privileges.
|
||||
|
||||
## Responsibility and typical access
|
||||
|
||||
| Responsibility | Typical GitHub access | Purpose |
|
||||
|---|---|---|
|
||||
| Product Owner | No automatic repository access implied | Product direction |
|
||||
| Organization Owner | Organization Owner | Organization administration and continuity |
|
||||
| Repository Admin | Admin | Repository settings, permissions, and protection rules |
|
||||
| Maintainer | Write by default | Implement, review, merge, and maintain |
|
||||
| Triage | Triage | Organize intake, de-duplicate, and prepare work |
|
||||
| Contributor / Platform Tester | Public / Read as appropriate | Contribute code or provide validation |
|
||||
|
||||
Maintain access may be granted when repository-management duties require it.
|
||||
|
||||
## Maintainer focus
|
||||
|
||||
- **Core Maintainer:** project-wide judgment, difficult technical decisions, governance support.
|
||||
- **Technical Maintainer:** implementation, architecture, validation, technical health.
|
||||
- **Project Maintainer:** review, contributor coordination, documentation, releases, organization.
|
||||
|
||||
These are responsibility labels. No label automatically changes GitHub permissions or overrides the [review rules](changes-and-review.md).
|
||||
|
||||
## Functional responsibilities
|
||||
|
||||
Maintainers may coordinate Release, Security, Infrastructure and CI, Community, or Test and Validation. These are duties, not ranks. For each release, designate one Release Maintainer and record the handoff if ownership changes.
|
||||
|
||||
## Least privilege and continuity
|
||||
|
||||
Grant access because it is necessary for current work, not because of a title. GitHub, Matrix, Plane, infrastructure, SSH, deployment systems, secrets, and external services are separate access surfaces.
|
||||
|
||||
For elevated or sensitive access, document a responsible owner and recovery route in an appropriate **private** administrative system. Do not publish tokens, SSH details, personal addresses, or credential locations in this handbook. Remove access promptly when it is no longer needed.
|
||||
|
||||
## Inactivity
|
||||
|
||||
Tell an admin when you expect to be unavailable; a communicated absence is fine.
|
||||
|
||||
If there is no meaningful maintainer or triage activity for **two months**, no prior notice, and no response to reasonable follow-up, elevated access may be reviewed and removed. This is access hygiene, not punishment. Returning members may regain access appropriate to their active responsibilities.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Testing and releases
|
||||
|
||||
Validation must match the actual change, and evidence must state what was **run**, **observed**, and **not tested**.
|
||||
|
||||
`dev` is the integration and stabilization branch. `main` is the curated release destination. Changes land in `dev`; a release promotes a verified `dev` revision to `main`.
|
||||
|
||||
## Runtime isolation
|
||||
|
||||
Run contributor-controlled tests, builds, installs, and repros in an isolated, secretless environment. Use disposable containers or microVMs where appropriate, with no credentials, sensitive host files, production data, or host/container-management sockets exposed. If safe isolation is unavailable, record the check as not run.
|
||||
|
||||
Agents may use a skill for the maintainer's preferred environment and handling; the same isolation requirements apply.
|
||||
|
||||
## Change validation
|
||||
|
||||
- Run focused tests that cover the modified behavior and failure cases.
|
||||
- Run broader regressions where risk crosses module boundaries.
|
||||
- For authentication, data loss, or similar high-risk work, include adversarial and rollback tests.
|
||||
- Reproduce the issue on the pre-fix version when safe and practical, then prove the correction.
|
||||
- For visual changes, run the application and attach the screenshots or clips required by [CONTRIBUTING.md](../../CONTRIBUTING.md).
|
||||
- Record exact commands, environment, result, skipped tests, and blockers. Never claim execution from a command you did not run.
|
||||
|
||||
GitHub Actions success means a workflow finished successfully; it does **not** mean CodeQL found no alerts. Use [review playbook](review-playbook.md#codeql-and-security-scanning) to assess findings separately. A review must tie required CI and the final diff to the **same commit SHA**.
|
||||
|
||||
## Supported-environment evidence
|
||||
|
||||
Platform Testers may validate without maintainer permissions. Useful coverage includes:
|
||||
|
||||
- Windows native and WSL.
|
||||
- macOS Apple Silicon.
|
||||
- macOS Intel while supported.
|
||||
- Linux native on the reference distribution.
|
||||
- Docker on supported hosts.
|
||||
|
||||
Record the environment and configuration for each result. Do not imply that a platform was tested when it was not.
|
||||
|
||||
## Release ownership
|
||||
|
||||
A designated **Release Maintainer** owns preparation and the publish decision once the release criteria are met. Other maintainers and testers supply the evidence needed for the change set. If the Release Maintainer becomes unavailable, another maintainer explicitly takes over.
|
||||
|
||||
## Release checklist
|
||||
|
||||
Before promoting `dev` to `main`:
|
||||
|
||||
1. Identify and freeze the release candidate SHA; check the actual content that will ship.
|
||||
2. Verify required checks and relevant supported-environment validation.
|
||||
3. Confirm high-risk and data-migration findings are resolved or addressed through an explicit approved plan.
|
||||
4. Document skipped coverage, known issues, compatibility and upgrade implications.
|
||||
5. Prepare the version, tag, artifacts, and release notes.
|
||||
6. Confirm rollback/recovery, including any manual persistence or data migration steps.
|
||||
7. Publish and record what was promoted, the verification evidence, and operational follow-ups.
|
||||
|
||||
Publishing does not require ceremonial Core or domain sign-off when the criteria are met. Exceptional or disputed releases follow the normal high-risk escalation path.
|
||||
@@ -0,0 +1,48 @@
|
||||
# Triage
|
||||
|
||||
Triage turns reports into evidence-backed work that a maintainer can pick up without guessing.
|
||||
|
||||
## Intake flow
|
||||
|
||||
```text
|
||||
Report
|
||||
-> reproduce / clarify
|
||||
-> identify duplicates and affected versions
|
||||
-> classify impact, urgency, and risk
|
||||
-> prepare actionable work item
|
||||
-> maintainer takes ownership
|
||||
-> PR, verification, and follow-up
|
||||
```
|
||||
|
||||
## A useful work item
|
||||
|
||||
Record what is known and distinguish it from what remains unverified:
|
||||
|
||||
- Original report and reproducible steps; installation method, OS, version/commit, and relevant environment.
|
||||
- Expected versus actual behavior, including user-visible impact.
|
||||
- Evidence: sanitized logs, screenshots, failing tests, or controlled reproduction.
|
||||
- Related issues, PRs, duplicates, or a known prior regression.
|
||||
- Scope, acceptance criteria, and non-goals.
|
||||
- Priority, ownership, and relevant domain expertise.
|
||||
- Remaining unknowns, risks, and safe recovery or workaround when available.
|
||||
|
||||
Small and obvious fixes may go straight to a focused PR, consistent with [CONTRIBUTING.md](../../CONTRIBUTING.md) and [changes and review](changes-and-review.md).
|
||||
|
||||
## Practical priority language
|
||||
|
||||
Use P0-P3 as **triage shorthand**, not as a substitute for verified exploitability or the project's actual GitHub labels:
|
||||
|
||||
| Priority | Typical impact | Expected response |
|
||||
|---|---|---|
|
||||
| P0 | Active exploitation, broad irreversible loss, catastrophic outage | Immediate containment and escalation |
|
||||
| P1 | Credible severe security or data-integrity vulnerability | Urgent owner assignment and validated fix |
|
||||
| P2 | Significant correctness, security, or operational regression | Prioritize and resolve before approving affected high-risk changes |
|
||||
| P3 | Limited impact, maintainability, or low-risk polish | Fix or explicitly track with rationale |
|
||||
|
||||
Do not call a concern harmless merely because an automated check is green. Escalate privately when reproduction would disclose a vulnerability.
|
||||
|
||||
## Where decisions live
|
||||
|
||||
Matrix is for coordination; durable decisions belong in GitHub, Plane, a specification, or the relevant PR. Keep confidential security and access details in appropriate private channels. Do not leave important project decisions only in chat history.
|
||||
|
||||
See the [review playbook](review-playbook.md) for converting triage into review evidence and handling contested or uncertain findings.
|
||||
Reference in New Issue
Block a user