diff --git a/Governance/policies/STALE_PRS.md b/Governance/policies/STALE_PRS.md new file mode 100644 index 00000000..7354a0f7 --- /dev/null +++ b/Governance/policies/STALE_PRS.md @@ -0,0 +1,121 @@ +# Stale PR Policy + +**Document:** `Governance/policies/STALE_PRS.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This policy defines what makes a pull request stale, the steps taken to nudge an author back into action, and the conditions under which a stale PR is closed. The goal is to keep the pull-request queue clean and actionable without discouraging contributors. + +--- + +## Scope + +This policy applies to all pull requests opened against `rinafcode/teachLink_backend`, regardless of target branch. + +--- + +## Staleness Threshold + +A pull request is considered **stale** when it has received **no activity for 30 calendar days**. Activity includes: + +- A commit pushed to the PR branch. +- A comment left by the author or any reviewer. +- A review submitted (approve, request changes, or comment). +- A label change by a maintainer. + +The 30-day window restarts every time any of the above activities occurs. + +--- + +## Nudge Steps + +When a PR becomes stale, the following sequence is followed: + +### Step 1 — Automated Stale Label (Day 30) + +The `status: stale` label is applied to the PR. An automated comment (or a maintainer comment) is posted: + +> *"This PR has been inactive for 30 days. It has been marked as stale. If you are still working on this, please leave a comment or push a new commit within 14 days to keep it open. If no activity is recorded, the PR will be closed on [date = Day 44]."* + +### Step 2 — Maintainer Review (Day 37) + +If there is still no activity 7 days after the stale label is applied, a maintainer checks whether: + +- The PR is blocked by something outside the author's control (e.g., an unresolved dependency). +- The PR could be taken over by another contributor. +- The PR should be closed without merge. + +The maintainer documents their assessment in a comment. + +### Step 3 — Closure (Day 44) + +If there is no activity for **14 calendar days** after the stale label is applied (44 days total since last activity), the PR is **closed** with the following comment: + +> *"Closing this PR due to inactivity. The branch and commits are preserved — please feel free to reopen or open a new PR when you are ready to continue. Thank you for your contribution."* + +The `status: stale` label remains on the closed PR for historical filtering. + +--- + +## Exceptions + +The following situations prevent the stale policy from applying: + +| Situation | Action | +|---|---| +| PR is labelled `status: on hold` | Stale timer is paused until the hold is lifted | +| PR is labelled `status: blocked` | Stale timer is paused; maintainer must document the blocker | +| PR is a draft (`Draft` state in GitHub) | Stale policy does not apply until converted to ready | +| PR is actively being reviewed | Stale timer restarts on each review action | + +--- + +## Reopen Path + +A closed stale PR may be reopened by: + +1. The original author, if the branch still exists and no conflicts have arisen. +2. Any contributor, by opening a **new PR** referencing the original. + +When reopening or creating a replacement PR, the author should: + +- Rebase onto the latest `main`. +- Resolve any review comments that were previously raised. +- Mention the original PR number for context (e.g., *"Replaces #456"*). + +There is no penalty for having a PR closed as stale. Contributions are always welcome. + +--- + +## Maintainer Responsibilities + +- Review the stale PR list as part of the weekly backlog review. +- Do not close PRs without leaving a clear, friendly closure comment. +- Consider whether a stale PR can be reassigned before closing. +- Ensure the `status: stale` label is removed if activity resumes before closure. + +--- + +## Metrics + +Maintainers should track the following monthly: + +- Number of PRs marked stale. +- Number of stale PRs closed vs. rescued (activity resumed). +- Average age of closed stale PRs. + +High stale rates may indicate onboarding friction, unclear contribution guidelines, or overly complex review requirements. + +--- + +## Related Documents + +- `Governance/policies/REVIEW_SLA.md` — Review SLA policy +- `Governance/processes/TRIAGE.md` — Issue triage process +- `Governance/LABEL_TAXONOMY.md` — Label definitions including `status: stale` +- `CONTRIBUTING.md` — General contribution guidelines diff --git a/Governance/processes/ROADMAP_GOVERNANCE.md b/Governance/processes/ROADMAP_GOVERNANCE.md new file mode 100644 index 00000000..4b48adf1 --- /dev/null +++ b/Governance/processes/ROADMAP_GOVERNANCE.md @@ -0,0 +1,135 @@ +# Roadmap Governance Process + +**Document:** `Governance/processes/ROADMAP_GOVERNANCE.md` +**Status:** Active +**Last Updated:** 2026-09-28 +**Owner:** Maintainer Team + +--- + +## Purpose + +This document defines how the TeachLink Backend public roadmap is proposed, approved, updated, and communicated. A transparent roadmap process helps contributors understand where the project is heading and how they can align their contributions with strategic priorities. + +--- + +## Scope + +This process applies to all roadmap planning activities for `rinafcode/teachLink_backend`. + +--- + +## What Is the Roadmap? + +The roadmap is the set of prioritised themes, features, and improvements planned for future milestones. It is not a binding delivery commitment — it is a directional guide that reflects current priorities. + +The roadmap lives as a GitHub project board and/or a `Governance/ROADMAP.md` file (updated quarterly). Both surfaces must stay in sync. + +--- + +## Roadmap Proposal Process + +### Who Can Propose Roadmap Items + +Any contributor or maintainer may propose a roadmap item by: + +1. Opening a GitHub issue labelled `type: feature` or `type: improvement` and `needs: discussion`. +2. Describing the problem, proposed solution, and expected impact. +3. Optionally proposing which milestone or quarter it belongs to. + +### Proposal Review + +Proposals are reviewed by maintainers during the **quarterly roadmap session** (see cadence below). Between sessions, high-impact proposals may be fast-tracked at the project lead's discretion. + +Proposal outcomes: + +| Outcome | Action | +|---|---| +| **Accepted** | Added to roadmap with a target milestone; issue labelled `status: triaged` | +| **Deferred** | Acknowledged but not scheduled; labelled `status: on hold` | +| **Declined** | Closed with a clear explanation of why it is out of scope | + +--- + +## Approval Process + +Roadmap items are approved by the following quorum: + +| Decision type | Required approvers | +|---|---| +| Add or remove a roadmap item | Project lead + 1 maintainer | +| Change the target milestone of an existing item | Any 1 maintainer | +| Publish a new quarterly roadmap | Project lead | +| Archive a past roadmap item | Any 1 maintainer | + +All roadmap approval decisions must be documented as a comment on the associated issue or as a commit to `Governance/ROADMAP.md`. + +--- + +## Roadmap Cadence + +| Activity | Frequency | Owner | +|---|---|---| +| Quarterly roadmap planning session | Once per quarter (first week of Jan, Apr, Jul, Oct) | Project Lead | +| Roadmap review and update | Monthly (first Monday) | Maintainer team | +| Roadmap published / communicated to community | After quarterly session | Project Lead | +| Individual item status update | When milestone is opened or closed | Assigned maintainer | + +--- + +## Roadmap Communication + +After each quarterly roadmap session, the project lead must: + +1. Update `Governance/ROADMAP.md` (if it exists) with the new set of priorities. +2. Post a summary in the [Telegram community](https://t.me/teachlinkOD). +3. Optionally publish a GitHub Discussions post for broader visibility. + +The communication must include: + +- Themes and features targeted for the upcoming quarter. +- Any items removed or deferred from the previous quarter and why. +- How contributors can get involved (which issues are open for pickup). + +--- + +## Roadmap Structure + +Each roadmap entry should capture: + +| Field | Description | +|---|---| +| **Title** | Brief, descriptive name of the item | +| **Status** | `Planned` / `In Progress` / `Completed` / `Deferred` | +| **Target milestone/quarter** | When it is expected to be worked on | +| **Priority** | `High` / `Medium` / `Low` | +| **Issue link** | Link to the GitHub issue | +| **Owner** | Assigned maintainer or `unassigned` | +| **Description** | 1–3 sentence explanation of the problem and value | + +--- + +## Changing the Roadmap + +The roadmap may be updated at any time, but changes must follow the approval requirements above. Ad-hoc changes between quarterly sessions must be documented with a reason. + +Roadmap items must not be silently removed. Any removal must include a comment on the associated issue explaining the decision. + +--- + +## Roles and Responsibilities + +| Role | Responsibility | +|---|---| +| **Project Lead** | Sets strategic direction; approves quarterly roadmap; communicates roadmap publicly | +| **Maintainer** | Reviews proposals; manages milestone assignments; updates roadmap entries | +| **Contributor** | Proposes items; picks up roadmap issues; keeps assigned items progressing | + +--- + +## Related Documents + +- `Governance/processes/MILESTONE_GOVERNANCE.md` — How milestones are created and managed +- `Governance/processes/TRIAGE.md` — How new issues are triaged into the roadmap +- `Governance/LABEL_TAXONOMY.md` — Labels used in roadmap proposals +- `CONTRIBUTING.md` — General contribution guidelines