From 66979a39af9129e5798b2e59b60483c28eb0e0f8 Mon Sep 17 00:00:00 2001 From: defiQUG Date: Mon, 9 Feb 2026 21:51:44 -0800 Subject: [PATCH] Initial commit: add .gitignore and README --- .gitignore | 49 +++++++ BRANCH_PROTECTION_POLICY.md | 265 ++++++++++++++++++++++++++++++++++++ IMPLEMENTATION_SCRIPT.md | 169 +++++++++++++++++++++++ README.md | 7 + 4 files changed, 490 insertions(+) create mode 100644 .gitignore create mode 100644 BRANCH_PROTECTION_POLICY.md create mode 100644 IMPLEMENTATION_SCRIPT.md create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4c64e16 --- /dev/null +++ b/.gitignore @@ -0,0 +1,49 @@ +# Dependencies +node_modules/ +.pnpm-store/ +vendor/ + +# Package manager lock files (optional: uncomment to ignore) +# package-lock.json +# yarn.lock + +# Environment and secrets +.env +.env.local +.env.*.local +*.env.backup +.env.backup.* + +# Logs and temp +*.log +logs/ +*.tmp +*.temp +*.tmp.* + +# OS +.DS_Store +Thumbs.db + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Build / output +dist/ +build/ +.next/ +out/ +*.pyc +__pycache__/ +.eggs/ +*.egg-info/ +.coverage +htmlcov/ + +# Optional +.reports/ +reports/ diff --git a/BRANCH_PROTECTION_POLICY.md b/BRANCH_PROTECTION_POLICY.md new file mode 100644 index 0000000..004c52a --- /dev/null +++ b/BRANCH_PROTECTION_POLICY.md @@ -0,0 +1,265 @@ +# 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] diff --git a/IMPLEMENTATION_SCRIPT.md b/IMPLEMENTATION_SCRIPT.md new file mode 100644 index 0000000..404abba --- /dev/null +++ b/IMPLEMENTATION_SCRIPT.md @@ -0,0 +1,169 @@ +# Branch Protection Implementation Script + +**Purpose**: Guide for implementing branch protection policies +**Version**: 1.0 +**Date**: 2025-01-27 + +--- + +## Prerequisites + +- Repository admin access +- Understanding of branch protection policy +- Access to repository settings + +--- + +## Implementation Checklist + +### Pre-Implementation + +- [ ] Review [BRANCH_PROTECTION_POLICY.md](./BRANCH_PROTECTION_POLICY.md) +- [ ] Identify main/master branch name +- [ ] Identify required CI/CD checks +- [ ] Identify code owners (if CODEOWNERS file exists) +- [ ] Communicate changes to team + +### GitHub Implementation + +#### Step 1: Navigate to Settings + +1. Go to repository +2. Click **Settings** +3. Click **Branches** in left sidebar + +#### Step 2: Add Protection Rule + +1. Click **Add rule** (or edit existing rule) +2. Branch name pattern: `main` (or `master`) + +#### Step 3: Configure Basic Protection + +- [x] **Require pull request reviews before merging** + - Required number of reviewers: `1` + - Dismiss stale pull request approvals when new commits are pushed: `Yes` + - Require review from Code Owners: `Yes` (if CODEOWNERS exists) + - Restrict pushes that create files: `No` (or `Yes` if desired) + +- [x] **Require status checks to pass before merging** + - Required status checks: [Select your CI/CD checks] + - Require branches to be up to date before merging: `Yes` + +- [x] **Require conversation resolution before merging**: `Yes` (recommended) + +- [x] **Require linear history**: `Yes` (recommended) + - Allow squash merging: `Yes` + - Allow merge commits: `No` (recommended) + - Allow rebase merging: `Yes` + +#### Step 4: Configure Restrictions + +- [x] **Do not allow bypassing the above settings**: `Yes` (recommended) +- [x] **Do not allow force pushes**: `Yes` +- [x] **Do not allow deletions**: `Yes` (for main/master) + +#### Step 5: Save + +1. Click **Create** (or **Save changes**) +2. Verify rule appears in list + +--- + +### GitLab Implementation + +#### Step 1: Navigate to Settings + +1. Go to repository +2. Click **Settings** → **Repository** +3. Expand **Protected branches** + +#### Step 2: Protect Branch + +1. Branch: Select `main` (or `master`) +2. Allowed to merge: `Maintainers` (or appropriate role) +3. Allowed to push: `No one` +4. Allowed to force push: `No` +5. Click **Protect** + +#### Step 3: Configure Merge Request Settings + +1. Go to **Settings** → **Merge requests** +2. Configure: + - Merge method: `Merge commit` or `Fast-forward merge` + - Squash commits when merging: `Yes` (optional) + - Delete source branch when merging: `Yes` (optional) + +--- + +## Verification + +After implementation: + +- [ ] Create test branch +- [ ] Attempt direct push to main/master (should fail) +- [ ] Create pull/merge request +- [ ] Verify review requirement +- [ ] Verify status check requirement +- [ ] Test merge process + +--- + +## Documentation + +After implementation: + +- [ ] Document protection status in repository README +- [ ] Link to branch protection policy +- [ ] Update team documentation +- [ ] Create exception request process (if needed) + +--- + +## Troubleshooting + +### Issue: Protection Rule Not Working + +**Solutions**: +- Verify rule applies to correct branch name +- Check if user has admin rights (can bypass) +- Verify rule is saved and active +- Check for conflicting rules + +### Issue: Status Checks Not Appearing + +**Solutions**: +- Verify CI/CD pipeline runs on branch +- Check status check names match exactly +- Verify status checks are required in settings +- Wait for CI/CD to complete (status checks appear after running) + +### Issue: Code Owner Reviews Not Required + +**Solutions**: +- Verify CODEOWNERS file exists in repository root +- Check CODEOWNERS file format +- Verify "Require review from Code Owners" is enabled +- Verify code owners have appropriate permissions + +--- + +## Post-Implementation Review + +After 1 week: + +- [ ] Review any issues/complaints +- [ ] Check for exception requests +- [ ] Verify process working smoothly +- [ ] Update documentation based on feedback + +--- + +## Script Version + +**Version**: 1.0 +**Last Updated**: 2025-01-27 +**Platforms Supported**: GitHub, GitLab + +--- + +**Note**: Adapt this script for your specific platform and requirements. diff --git a/README.md b/README.md new file mode 100644 index 0000000..51bd765 --- /dev/null +++ b/README.md @@ -0,0 +1,7 @@ +# branch-protection + +Project under `/home/intlc/projects/branch-protection`. + +## Overview + +(Add project description and setup instructions here.)