Skip to content

docs(governance): add backport policy (Backport Policy for release branches) - #1743

Merged
RUKAYAT-CODER merged 1 commit into
rinafcode:mainfrom
iyanumajekodunmi756:docs/issue-1624-backport-policy
Sep 30, 2026
Merged

RUKAYAT-CODER merged 1 commit into
rinafcode:mainfrom
iyanumajekodunmi756:docs/issue-1624-backport-policy

Conversation

@iyanumajekodunmi756

Copy link
Copy Markdown

Summary

Adds a versioned backport policy for TeachLink Backend, closing the governance gap identified in #1624. The Governance/policies/ folder had no reference for how fixes move from the current development line to older release branches; this document makes backporting predictable instead of an ad-hoc negotiation during an incident.

Per the issue's implementation plan, the policy documents:

  • Which branches receive backports (§2): main (hotfixes and forward-ports), release/x.y stabilisation branches, and published release/x.y.z maintenance lines, with rules that only supported lines are eligible, backports branch from the fork point, no forward drift is allowed, and cherry-picks are made with -x to record the source commit.
  • Eligibility criteria (§3): the fix must already be merged upstream, correct a real defect or exposure, impact consumers of that line, be low-regression-risk (PATCH-level under VERSIONING.md), carry regression tests with green suites on the target line, and have a tracked issue or advisory.
  • Approval process (§4): tracking-issue proposal → maintainer triage recorded on the issue → backport branch from the target line (backport/x.y/issue-<N>-<slug>) → PR against the release branch with two maintainer approvals including a code owner for hotfix paths and author/approver independence → required CI (lint, format, typecheck, build, migrations, tests) with no skipped checks → merge, changelog entry, and mandatory forward-port so lines never silently diverge.
  • Expedited handling only through the existing hotfix and security processes; gates are never waived.

Changes

File Change
Governance/policies/BACKPORT.md New backport policy (backport targets, eligibility criteria, approval process, relationship to other policies, change log)
Governance/README.md Adds Backport Policy to the versioned policies index

Scope: exactly two files, both under Governance/. No changes anywhere else in the repository, satisfying the issue's acceptance criteria.

Consistency with existing governance

  • Follows the document format of the recently merged policies (DEPRECATION.md, CREDITS.md): Status/Version/Owner/Last reviewed header, numbered sections, and a version-table change log (v1.0.0).
  • Aligns with the branch model in CONTRIBUTING.md §3/§11 (main, develop, hotfix/*, back-merge rule), the hotfix gates in Governance/processes/HOTFIX.md, approval counts in policies/APPROVAL_REQUIREMENTS.md, PATCH semantics in policies/VERSIONING.md §7, changelog requirements in policies/CHANGELOG_POLICY.md, and supported-line rules in SECURITY_POLICY.md.
  • Cross-references rather than duplicates: each related policy owns its subject, and the document states that the more specific document prevails on conflict.

Regression tests

Not applicable — documentation-only change. It adds two Markdown files and modifies no TypeScript, configuration, schema, or dependency. Governance/ is outside the Jest root (rootDir: 'src'), outside the TypeScript build (tsconfig.build.json compiles src/), and no existing test, build step, or runtime path is affected.

Local CI verification

All CI-equivalent checks from .github/workflows/ci.yml run locally on this branch:

Check Command Result
Lint pnpm run lint:ci ✅ Pass (0 errors, 0 warnings)
Typecheck pnpm run typecheck ✅ Pass
Build pnpm run build ✅ Pass
Migrations static check pnpm run migrations:check ✅ Pass (all 53 migrations)
No build artifacts guard git ls-files 'dist/' '*.tsbuildinfo' ✅ Empty

The remaining CI jobs (migration:run, drift check, revert, test suites, security scan) require a provisioned PostgreSQL service and exercise application code; none are affected by a Markdown-only change under Governance/.

Acceptance criteria

  • Governance requirement implemented (BACKPORT.md with backport branches, eligibility criteria, and approval process)
  • Scope limited to a maximum of two files
  • No changes outside the Governance/ folder
  • No regression in existing functionality (documentation-only; no code, config, or dependency touched)
  • Tests pass and code follows project standards (lint, typecheck, build, migrations check all green locally)
  • Change documented (policy includes change log; indexed in Governance/README.md)

Closes #1624

Adds Governance/policies/BACKPORT.md defining which branches receive
backports (main, release/x.y, published release lines), the eligibility
criteria a fix must meet before it is backported, and the approval
process (tracking issue, maintainer triage, two maintainer approvals
with review independence, required CI, changelog entry, and mandatory
forward-port). Links it from the Policies index in Governance/README.md
and cross-references HOTFIX, APPROVAL_REQUIREMENTS, VERSIONING,
CHANGELOG_POLICY, and SECURITY_POLICY.

Closes rinafcode#1624

🤖 Generated with Codebuff
Co-Authored-By: Codebuff <noreply@codebuff.com>
@drips-wave

drips-wave Bot commented Sep 30, 2026

Copy link
Copy Markdown

@iyanumajekodunmi756 Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@RUKAYAT-CODER

Copy link
Copy Markdown
Contributor

Thank you for contributing to the project.

@RUKAYAT-CODER
RUKAYAT-CODER merged commit 40f8b5c into rinafcode:main Sep 30, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add a backport policy for TeachLink Backend

2 participants