branch-protection/BRANCH_PROTECTION_POLICY.md

Branch Protection Policy for Tier-1 Canonical Systems

Version: 1.0 Date: 2025-01-27 Status: Recommended Policy

---

Overview

This document defines the recommended branch protection policies for Tier-1 canonical system repositories to enforce the constitutional governance framework.

---

Applicable Repositories

This policy applies to:

• dbis_core
• iccc_monorepo
• smom-dbis-138
• smoa

---

Protection Levels

Level 1: Standard Protection (All Branches)

Applies to all branches:

• Require Pull Request Reviews

  • Required reviewers: 1
  • Dismiss stale reviews: Yes
  • Require review from code owners: Yes (if CODEOWNERS exists)

• Require Status Checks

  • CI/CD checks must pass
  • Required status checks: [Configure based on CI/CD setup]

• Restrict Push Access

  • Allow force pushes: No
  • Allow deletions: No (for main/master only)

Level 2: Enhanced Protection (Main/Master Branch)

Additional protections for main/master branch:

• Require Linear History

  • Allow squash merging: Yes
  • Allow merge commits: No (preferred) or Restricted
  • Allow rebase merging: Yes

• Require Branch to be Up to Date

  • Require branches to be up to date before merging: Yes

• Lock Branch

  • Lock branch: No (only for emergency maintenance)

---

Governance-Specific Protections

Tier-1 Change Detection

For changes that require formal proposals:

• Proposal Reference Check (if automated)

  • Verify proposal ID in commit message or PR description
  • Format: PROPOSAL-YYYY-MMDD-NNN or proposal: PROPOSAL-YYYY-MMDD-NNN

• Constitutional Change Detection

  • If CANONICAL_CONSTITUTION.md modified, require:
    • Proposal ID in PR
    • Amendment log update
    • Version increment

Recognition Verification (Manual Process)

• Reviewer Guidelines: Reviewers should verify:
  • Proposal exists in proposals/ directory
  • Proposal shows recognition from all Tier-1 systems
  • Change aligns with approved proposal
  • Documentation updates included

---

Exception Process

Emergency Changes

For critical security/stability issues:

1. Emergency Declaration

   • Create issue/note declaring emergency
   • Justify emergency status
   • Tag with emergency label

2. Expedited Review

   • Reduced review requirements (still require review)
   • Fast-track approval process
   • Document emergency in commit/PR

3. Post-Implementation

   • Submit formal proposal retrospectively
   • Document emergency in proposal
   • Update tracking

Bypass Procedure

If branch protection must be temporarily bypassed:

1. Justification Required

   • Document reason for bypass
   • Get approval from repository maintainers
   • Create issue documenting bypass

2. Post-Bypass Review

   • Review changes made
   • Verify compliance
   • Document in issue

3. Prevent Future Need

   • Identify process improvements
   • Update procedures if needed

---

Implementation Steps

Step 1: Configure Basic Protection

1. Navigate to repository Settings → Branches
2. Add branch protection rule for main (or master)
3. Configure basic settings:
   • Require pull request reviews
   • Require status checks
   • Restrict force pushes

Step 2: Configure Enhanced Protection

1. Add linear history requirement
2. Require branch up to date
3. Configure merge options

Step 3: Document Policy

1. Link to this policy in repository
2. Update README with protection information
3. Document exception process

Step 4: Train Team

1. Share policy with repository maintainers
2. Explain protection rules
3. Document exception process

---

Platform-Specific Notes

GitHub

Settings location: Settings → Branches → Branch protection rules

Key settings:

• Require pull request reviews before merging
• Require status checks to pass before merging
• Require branches to be up to date before merging
• Do not allow force pushes
• Do not allow deletions

GitLab

Settings location: Settings → Repository → Protected branches

Key settings:

• Allowed to merge: Maintainers (or appropriate role)
• Allowed to push: No one
• Allowed to force push: No

Other Platforms

Adapt settings based on platform capabilities while maintaining core principles:

• Require reviews
• Prevent force pushes
• Require status checks

---

Monitoring and Enforcement

Regular Review

• Quarterly review of protection settings
• Verify rules still appropriate
• Check for bypasses/exceptions
• Review exception frequency

Compliance

• Ensure all Tier-1 repos have protection
• Verify protection rules active
• Document any exceptions
• Track bypass requests

---

Recommended Branch Strategy

Main/Master Branch

• Purpose: Production-ready code
• Protection: Full Level 2 protection
• Merges: Via pull requests only
• Requirements: All checks pass, reviews approved

Development/Feature Branches

• Purpose: Active development
• Protection: Level 1 protection (if applicable)
• Merges: To main/master via PR
• Requirements: Standard review process

Release Branches

• Purpose: Release preparation
• Protection: Level 2 protection
• Merges: From main, to main only
• Requirements: Release process compliance

---

Documentation Requirements

Each repository should document:

1. Branch Protection Status

   • Which branches are protected
   • Protection level
   • How to request exceptions

2. Review Process

   • Who can review
   • Review requirements
   • Approval process

3. Exception Process

   • How to request exceptions
   • Emergency procedures
   • Bypass documentation

---

Reference Documents

• CANONICAL_CONSTITUTION.md - Constitutional framework
• CANONICAL_CHANGE_CONTROL_PROCESS.md - Change control
• CANONICAL_GOVERNANCE_GUIDE.md - Governance guide

---

Policy Version: 1.0 Last Updated: 2025-01-27 Review Date: [Quarterly review recommended]