266 lines
6.1 KiB
Markdown
266 lines
6.1 KiB
Markdown
# 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](../CANONICAL_CONSTITUTION.md)** - Constitutional framework
|
|
- **[CANONICAL_CHANGE_CONTROL_PROCESS.md](../CANONICAL_CHANGE_CONTROL_PROCESS.md)** - Change control
|
|
- **[CANONICAL_GOVERNANCE_GUIDE.md](../CANONICAL_GOVERNANCE_GUIDE.md)** - Governance guide
|
|
|
|
---
|
|
|
|
**Policy Version**: 1.0
|
|
**Last Updated**: 2025-01-27
|
|
**Review Date**: [Quarterly review recommended]
|