From 3ed0c6d1808c3fe74ee860ac04da4136fea31df8 Mon Sep 17 00:00:00 2001 From: Blaqkenny Date: Mon, 28 Sep 2026 12:21:55 +0000 Subject: [PATCH] docs(governance): add label taxonomy, triage process, review SLA, and milestone governance Closes rinafcode/teachLink_backend#1601 Closes rinafcode/teachLink_backend#1602 Closes rinafcode/teachLink_backend#1603 Closes rinafcode/teachLink_backend#1604 - Add Governance/policies/REVIEW_SLA.md with first-response (2 days), review-completion (5 days), follow-up (3 days) targets, escalation path, and exception handling (#1601) - Add Governance/processes/TRIAGE.md with 7-step triage workflow, required labels, triage cadence, and stale issue handling (#1602) - Add Governance/LABEL_TAXONOMY.md defining type, priority, status, area, needs, and programme label categories with colour codes, descriptions, and application rules (#1603) - Add Governance/processes/MILESTONE_GOVERNANCE.md with entry/exit criteria, milestone creation rules, naming conventions, and owner responsibilities (#1604) --- Governance/LABEL_TAXONOMY.md | 152 +++++++++++++++++++ Governance/policies/REVIEW_SLA.md | 109 +++++++++++++ Governance/processes/MILESTONE_GOVERNANCE.md | 137 +++++++++++++++++ Governance/processes/TRIAGE.md | 123 +++++++++++++++ 4 files changed, 521 insertions(+) create mode 100644 Governance/LABEL_TAXONOMY.md create mode 100644 Governance/policies/REVIEW_SLA.md create mode 100644 Governance/processes/MILESTONE_GOVERNANCE.md create mode 100644 Governance/processes/TRIAGE.md diff --git a/Governance/LABEL_TAXONOMY.md b/Governance/LABEL_TAXONOMY.md new file mode 100644 index 00000000..e6c6129a --- /dev/null +++ b/Governance/LABEL_TAXONOMY.md @@ -0,0 +1,152 @@ +# Label Taxonomy + +**Document:** `Governance/LABEL_TAXONOMY.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This document defines all labels used in the TeachLink Backend repository, their intended meaning, and the rules for applying them. A consistent label taxonomy makes triage, filtering, and reporting predictable for contributors and maintainers alike. + +--- + +## Label Categories + +Labels are organised into the following categories. Each category uses a consistent prefix so labels can be quickly filtered in the GitHub UI. + +--- + +### 1. Type Labels (`type:`) + +Classify *what kind of issue or PR* this is. + +| Label | Colour | Description | +|---|---|---| +| `type: bug` | `#D73A4A` (red) | Existing functionality is broken or behaving incorrectly | +| `type: feature` | `#0075CA` (blue) | A new capability is being requested | +| `type: improvement` | `#A2EEEF` (teal) | Enhancement to existing behaviour without adding new capabilities | +| `type: docs` | `#0075CA` (blue) | Documentation gap, error, or improvement | +| `type: governance` | `#5319E7` (purple) | Policy, process, or governance document | +| `type: chore` | `#E4E669` (yellow) | Maintenance, dependency updates, CI, tooling, refactoring | +| `type: question` | `#D876E3` (pink) | General question; consider redirecting to Telegram | +| `type: security` | `#B60205` (dark red) | Security-related finding or hardening task | +| `type: performance` | `#FEF2C0` (cream) | Performance regression or optimisation task | + +**Rules:** +- Apply exactly **one** `type:` label per issue or PR. +- If an issue spans multiple types, choose the primary intent. + +--- + +### 2. Priority Labels (`priority:`) + +Indicate *how urgently* the issue or PR needs attention. + +| Label | Colour | Criteria | +|---|---|---| +| `priority: critical` | `#B60205` (dark red) | Production broken, security vulnerability, or data-loss risk | +| `priority: high` | `#E11D48` (rose) | Major feature blocked or significant user impact | +| `priority: medium` | `#FBCA04` (amber) | Noticeable issue; a workaround exists | +| `priority: low` | `#C2E0C6` (light green) | Minor inconvenience; cosmetic or edge-case | + +**Rules:** +- Apply exactly **one** `priority:` label per issue or PR. +- Critical issues must be escalated immediately to `@rinafcode/maintainers`. + +--- + +### 3. Status Labels (`status:`) + +Communicate *where the issue or PR currently stands* in the workflow. + +| Label | Colour | Description | +|---|---|---| +| `status: needs triage` | `#EDEDED` (grey) | Issue has not been reviewed by a maintainer yet | +| `status: triaged` | `#0E8A16` (green) | Issue has been reviewed and categorised | +| `status: in progress` | `#0075CA` (blue) | Someone is actively working on this | +| `status: blocked` | `#D73A4A` (red) | Work is blocked by a dependency or decision | +| `status: on hold` | `#E4E669` (yellow) | Intentionally paused pending a decision | +| `status: stale` | `#EDEDED` (grey) | No activity for 60+ days | +| `status: wontfix` | `#FFFFFF` (white) | Acknowledged but out of scope; will not be addressed | +| `status: duplicate` | `#CFD3D7` (light grey) | Duplicate of an existing issue | + +**Rules:** +- Every open issue should carry one `status:` label. +- Only maintainers may apply `status: wontfix`. + +--- + +### 4. Area Labels (`area:`) + +Identify *which part of the codebase or domain* is affected. + +| Label | Colour | Description | +|---|---|---| +| `area: auth` | `#1D76DB` (dark blue) | Authentication and authorisation | +| `area: api` | `#0075CA` (blue) | REST or GraphQL API surface | +| `area: database` | `#5319E7` (purple) | Database schema, migrations, queries | +| `area: ci-cd` | `#E4E669` (yellow) | CI/CD pipelines and automation | +| `area: docs` | `#A2EEEF` (teal) | Documentation and README | +| `area: payments` | `#0E8A16` (green) | Payments and Stripe integration | +| `area: notifications` | `#D876E3` (pink) | Notifications module | +| `area: search` | `#FEF2C0` (cream) | Search and Elasticsearch | +| `area: governance` | `#5319E7` (purple) | Governance documents and processes | +| `area: security` | `#B60205` (dark red) | Security hardening and vulnerabilities | +| `area: infra` | `#FBCA04` (amber) | Infrastructure and deployment | + +**Rules:** +- Apply one or more `area:` labels as appropriate. +- Create a new `area:` label if a consistently relevant area is missing (requires maintainer approval). + +--- + +### 5. Needs Labels (`needs:`) + +Signal *what the issue is waiting on* before it can move forward. + +| Label | Colour | Description | +|---|---|---| +| `needs: more info` | `#EDEDED` (grey) | Waiting for clarification from the author | +| `needs: design` | `#FEF2C0` (cream) | Requires a design or architecture decision first | +| `needs: discussion` | `#D876E3` (pink) | Open question requiring broader team input | +| `needs: review` | `#0075CA` (blue) | PR is ready for review | +| `needs: rebase` | `#E4E669` (yellow) | PR has conflicts and needs to be rebased | + +--- + +### 6. Programme Labels + +Used by specific open-source or contribution programmes. + +| Label | Colour | Description | +|---|---|---| +| `Stellar Wave` | `#5555FF` (blue-purple) | Part of the Stellar Wave contributor programme | +| `good first issue` | `#7057FF` (purple) | Suitable for first-time contributors | +| `help wanted` | `#008672` (teal) | Extra help is welcome; not reserved for a specific person | + +--- + +## Rules for Applying Labels + +1. **Triage first:** Do not apply labels before triaging. `status: needs triage` is the default. +2. **Minimum required labels:** After triage, every issue must have at least one `type:`, one `priority:`, and `status: triaged`. +3. **Keep labels current:** Update status labels as the issue progresses. A closed issue should not retain `status: in progress`. +4. **No label spam:** Do not apply labels that are not relevant. Noisy labels obscure filters. +5. **Label creation:** New labels must be proposed via a PR to this document before being created in GitHub. + +--- + +## Label Maintenance + +Labels should be reviewed quarterly. Unused labels (no issues in 6 months) should be archived. Renamed labels must update all existing issues. + +--- + +## Related Documents + +- `Governance/processes/TRIAGE.md` — Issue triage process +- `Governance/processes/MILESTONE_GOVERNANCE.md` — Milestone governance +- `CONTRIBUTING.md` — General contribution guidelines diff --git a/Governance/policies/REVIEW_SLA.md b/Governance/policies/REVIEW_SLA.md new file mode 100644 index 00000000..5eb4a78a --- /dev/null +++ b/Governance/policies/REVIEW_SLA.md @@ -0,0 +1,109 @@ +# Review SLA Policy + +**Document:** `Governance/policies/REVIEW_SLA.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This policy defines the expected response and review-completion timescales for pull requests submitted to the TeachLink Backend repository. It ensures contributors receive timely feedback and that the review queue does not stall. + +--- + +## Scope + +This policy applies to all pull requests opened against `rinafcode/teachLink_backend`, regardless of branch target (`main` or `develop`). + +--- + +## SLA Targets + +| Review Stage | Target Timeframe | Measured From | +|---|---|---| +| First-response acknowledgement | **2 business days** | PR opened | +| Substantive review (comments or approval) | **5 business days** | PR opened | +| Follow-up review after changes requested | **3 business days** | Author pushes requested changes | +| Final approval or rejection | **7 business days** | PR opened | + +> **Business days** are Monday–Friday, excluding public holidays. Weekends and holidays do not count toward SLA timers. + +--- + +## First-Response Target + +A reviewer **must** leave at least one of the following within **2 business days** of a PR being opened: + +- An approval +- A change request with at least one actionable comment +- A neutral comment acknowledging receipt (e.g., *"Queued for review — will respond in full by [date]"*) + +Silently leaving a PR in the queue without any acknowledgement beyond the 2-day window is a policy breach. + +--- + +## Review-Completion Target + +A full, substantive review must be completed within **5 business days** of the PR being opened. + +A "complete review" means: + +1. All files have been inspected. +2. A verdict has been recorded: **Approve**, **Request Changes**, or **Comment**. +3. Any blocking issues are described clearly and actionably. + +--- + +## Escalation Path + +If SLA targets are not met, the following escalation steps apply: + +1. **Day 6 (after PR open):** The PR author may ping the reviewer directly in the PR comments, tagging `@rinafcode/maintainers`. +2. **Day 8:** The author may escalate to the project lead via the [Telegram community](https://t.me/teachlinkOD) or by opening a discussion. +3. **Day 10:** A co-maintainer may self-assign the review and complete it independently. + +Escalation should remain professional. The goal is to unblock the contributor, not to assign blame. + +--- + +## Reviewer Responsibilities + +- Reviewers should not approve PRs they have not read thoroughly. +- Reviewers must leave clear, actionable feedback when requesting changes. +- Reviewers should acknowledge when a PR is out of their expertise and reassign accordingly. + +--- + +## Author Responsibilities + +- Authors must respond to change requests within **5 business days** to keep the PR active. +- Authors must keep PRs reasonably scoped (prefer small, focused changes) to make timely reviews feasible. +- Authors must ensure CI passes before requesting review. + +--- + +## Exceptions + +The following situations may extend the SLA without breach: + +- Maintainer has announced a leave of absence. +- PR requires specialist knowledge not currently available in the team. +- PR is intentionally placed on hold pending a design decision (must be labelled `status: on-hold`). + +Exceptions must be documented in the PR as a comment. + +--- + +## Compliance + +Maintainers are expected to self-monitor SLA adherence. The project lead will review aggregate SLA data quarterly and take corrective action if systemic delays are observed. + +--- + +## Related Documents + +- `Governance/processes/TRIAGE.md` — Issue triage process +- `Governance/policies/STALE_PRS.md` — Policy for closing stale pull requests +- `CONTRIBUTING.md` — General contribution guidelines diff --git a/Governance/processes/MILESTONE_GOVERNANCE.md b/Governance/processes/MILESTONE_GOVERNANCE.md new file mode 100644 index 00000000..fb41babd --- /dev/null +++ b/Governance/processes/MILESTONE_GOVERNANCE.md @@ -0,0 +1,137 @@ +# Milestone Governance Process + +**Document:** `Governance/processes/MILESTONE_GOVERNANCE.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This document defines how milestones are created, managed, and closed for the TeachLink Backend repository. A clear milestone governance process ensures that release planning is transparent, that issues are properly scoped per milestone, and that contributors understand what is targeted for each release. + +--- + +## Scope + +This process applies to all milestones created in `rinafcode/teachLink_backend`. + +--- + +## Milestone Creation + +### Who Can Create Milestones + +Only maintainers (members of `@rinafcode/maintainers`) may create milestones. Contributors may propose a milestone by opening a discussion issue tagged `type: governance`. + +### When to Create a Milestone + +A milestone should be created when: + +- A new release version is being planned (e.g., `v1.2.0`). +- A thematic batch of work is being tracked (e.g., `Security Hardening Sprint`). +- A time-boxed programme of contributions is starting (e.g., `Stellar Wave Q3 2026`). + +### Required Fields + +Every milestone must be created with: + +| Field | Requirement | +|---|---| +| **Title** | Descriptive and versioned where applicable (e.g., `v1.3.0 – Search Improvements`) | +| **Due date** | A realistic target date (mandatory; use best estimate if exact date is unknown) | +| **Description** | A 1–3 sentence summary of the milestone's goal and scope | + +--- + +## Entry Criteria + +An issue or PR may be assigned to a milestone when **all** of the following are true: + +1. The issue has been triaged (carries the `triaged` label). +2. The issue is within the milestone's defined scope. +3. The work can realistically be completed before the milestone due date. +4. A contributor is either assigned or has expressed intent to work on it. + +Issues that do not meet entry criteria must not be added to the milestone. + +--- + +## Milestone Management + +### Adding Issues + +Maintainers add issues to a milestone during: + +- **Milestone planning sessions** — held when a new milestone is opened. +- **Weekly backlog reviews** — newly triaged issues assessed for fit. + +Issues must not be added to a closed milestone. + +### Removing Issues + +An issue must be removed from a milestone (returned to backlog) if: + +- It is determined to be out of scope. +- The contributor assigned to it is no longer available and no replacement is found within 5 business days. +- A dependency blocker means it cannot be completed before the due date. + +When removing an issue, a maintainer must leave a comment explaining why it was descoped. + +### Milestone Due Date Changes + +Due dates may be extended by a maintainer if: + +- More than 20% of milestone issues are blocked. +- An unforeseen high-priority issue consumes significant capacity. + +Due date changes must be announced in the milestone description with a reason and the new date. + +--- + +## Exit Criteria + +A milestone may be closed when **all** of the following are true: + +1. All issues assigned to the milestone are either closed or explicitly descoped with a comment. +2. All PRs associated with the milestone are either merged or closed. +3. A release (if applicable) has been tagged and published. +4. A milestone summary comment has been posted (see below). + +### Milestone Summary Comment + +Before closing a milestone, a maintainer must post a comment on the milestone (via GitHub's milestone interface) or in the linked discussion containing: + +- Total issues completed vs. total scoped. +- Any notable descoped items and why. +- Lessons learned (optional but encouraged). + +--- + +## Milestone Naming Convention + +| Type | Format | Example | +|---|---|---| +| Release | `vMAJOR.MINOR.PATCH – Short description` | `v1.3.0 – Payment Module Refactor` | +| Sprint / Theme | `[Theme] Sprint – Short description` | `Security Hardening Sprint – Q4 2026` | +| Programme | `[Programme Name] Batch N` | `Stellar Wave Batch 3` | + +--- + +## Roles and Responsibilities + +| Role | Responsibility | +|---|---| +| **Project Lead** | Approves milestone creation; sets strategic priorities | +| **Maintainer** | Creates, manages, and closes milestones; triages issues into milestones | +| **Contributor** | Picks up assigned issues; communicates blockers promptly | + +--- + +## Related Documents + +- `Governance/processes/TRIAGE.md` — How issues are triaged before milestone assignment +- `Governance/LABEL_TAXONOMY.md` — Labels used during triage and milestone management +- `Governance/policies/REVIEW_SLA.md` — Review timelines affecting milestone velocity +- `CONTRIBUTING.md` — General contribution guidelines diff --git a/Governance/processes/TRIAGE.md b/Governance/processes/TRIAGE.md new file mode 100644 index 00000000..6c1d7c7b --- /dev/null +++ b/Governance/processes/TRIAGE.md @@ -0,0 +1,123 @@ +# Issue Triage Process + +**Document:** `Governance/processes/TRIAGE.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This document defines the process for triaging newly opened issues in the TeachLink Backend repository. Triage ensures every issue is assessed, categorised, and routed promptly so contributors and maintainers can act on it without ambiguity. + +--- + +## Scope + +This process applies to all issues opened against `rinafcode/teachLink_backend`. + +--- + +## Triage Steps + +### Step 1 — Acknowledge the Issue + +Within **2 business days** of an issue being opened, a maintainer must: + +- Post a comment acknowledging receipt (can be brief: *"Thanks, triaging this now."*) +- Assign themselves or another maintainer as the triager. + +### Step 2 — Validate the Issue + +The triager checks whether the issue is: + +| Outcome | Action | +|---|---| +| **Duplicate** | Close with `duplicate` label, link to original | +| **Out of scope** | Close with `wontfix` + brief explanation | +| **Needs more information** | Add `needs: more info` label, request clarification from author | +| **Valid** | Proceed to Step 3 | + +### Step 3 — Classify the Issue + +Apply the appropriate **type** label: + +| Label | When to use | +|---|---| +| `type: bug` | Existing functionality is broken or behaves incorrectly | +| `type: feature` | New capability is being requested | +| `type: improvement` | Enhancement to existing functionality | +| `type: docs` | Documentation gap or error | +| `type: governance` | Policy, process, or governance document | +| `type: chore` | Maintenance, dependency update, CI, tooling | +| `type: question` | General question (consider redirecting to Telegram) | + +### Step 4 — Assign Priority + +Apply exactly one **priority** label: + +| Label | Criteria | +|---|---| +| `priority: critical` | Production broken, security vulnerability, data loss risk | +| `priority: high` | Major feature blocked, significant user impact | +| `priority: medium` | Noticeable issue; a workaround exists | +| `priority: low` | Minor inconvenience; cosmetic or edge-case | + +### Step 5 — Assign to a Milestone (if applicable) + +If the issue fits an active milestone, assign it. If not, leave the milestone field empty; the issue will be picked up during the next roadmap review. + +### Step 6 — Assign a Contributor (if applicable) + +If a specific contributor is best placed to handle the issue (or has expressed interest), assign them. Otherwise leave unassigned so the community can self-select. + +### Step 7 — Add the `triaged` Label + +Once Steps 1–6 are complete, add the `triaged` label. This signals that the issue is ready to be picked up. + +--- + +## Triage Cadence + +| Activity | Frequency | +|---|---| +| New issue triage | Within 2 business days of opening | +| Backlog review | Weekly (every Monday) | +| Stale issue sweep | Monthly (first Monday of the month) | + +--- + +## Required Labels After Triage + +Every triaged issue must have: + +1. One `type:` label +2. One `priority:` label +3. The `triaged` label + +Issues missing any of these after 5 business days should be flagged in the weekly backlog review. + +--- + +## Stale Issues + +An issue is considered stale if it has had no activity for **60 days**. Stale issues should be: + +1. Commented on to check continued relevance. +2. Closed with `status: stale` if no response is received within **14 days**. + +--- + +## Escalation + +If a high or critical priority issue has not been triaged within **1 business day**, any contributor may escalate by tagging `@rinafcode/maintainers` in the issue comments. + +--- + +## Related Documents + +- `Governance/LABEL_TAXONOMY.md` — Full label definitions +- `Governance/processes/MILESTONE_GOVERNANCE.md` — Milestone assignment rules +- `Governance/policies/REVIEW_SLA.md` — Review SLA for pull requests +- `CONTRIBUTING.md` — General contribution guidelines