From 5f4a0a703b5f567429be68b67c4320ad33318b66 Mon Sep 17 00:00:00 2001 From: Menjay7 Date: Fri, 16 Oct 2026 18:00:10 +0100 Subject: [PATCH] https://github.com/Menjay7/teachLink_web.git --- .github/merge-strategy.md | 146 ++++++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 2 + README.md | 2 + 3 files changed, 150 insertions(+) create mode 100644 .github/merge-strategy.md diff --git a/.github/merge-strategy.md b/.github/merge-strategy.md new file mode 100644 index 00000000..27db5cff --- /dev/null +++ b/.github/merge-strategy.md @@ -0,0 +1,146 @@ +# Merge Strategy Policy + +This document defines the merge strategy and conventions for the TeachLink Web repository. + +## GitHub Repository Settings + +Configure merge settings under: **Settings → General → Pull Requests** + +### Merge Method + +**Primary merge method: Squash and merge** + +- ✅ **Allow squash merging** +- ❌ **Allow merge commits** (disabled) +- ❌ **Allow rebase merging** (disabled) + +### Rationale for Squash Merge + +- **Cleaner history**: Each PR becomes a single commit in the target branch +- **Easier bisecting**: Commits are atomic and self-contained +- **Consistent messages**: PR title/description become the commit message +- **Reduced noise**: WIP commits, typo fixes, and rebases are hidden + +### Update Strategy + +- ✅ **Automatically delete head branches** after merge +- ✅ **Allow auto-merge** (optional, with admin approval) + +## Commit Message Conventions + +### PR Title Format + +PR titles should follow conventional commits format: + +``` +(): +``` + +**Types:** +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `style`: Code style changes (formatting, no logic change) +- `refactor`: Code refactoring +- `perf`: Performance improvements +- `test`: Test additions/changes +- `chore`: Maintenance tasks +- `ci`: CI/CD changes +- `build`: Build system changes + +**Examples:** +- `feat(auth): add OAuth2 login support` +- `fix(profile): resolve avatar upload failure` +- `refactor(api): consolidate user endpoints` + +### Squashed Commit Message + +When squashing, GitHub uses the PR title as the commit message. Ensure: +- PR title is descriptive and follows the format above +- PR description provides context (this becomes the commit body) +- Include issue reference in PR description (e.g., `Closes #123`) + +## Merge Workflow + +### For Feature Branches + +1. **From `develop` to `main`** + - Squash merge + - Requires PR approval (1-2 reviewers) + - Requires CI checks to pass + - Must be up-to-date with `main` + +2. **From feature branch to `develop`** + - Squash merge + - Requires PR approval (1 reviewer) + - Requires CI checks to pass + - Must be up-to-date with `develop` + +### For Hotfix Branches + +1. **Hotfix workflow** + - Create branch from `main`: `hotfix/` + - After fix, squash merge to `main` + - Then squash merge to `develop` to propagate fix + +### For Release Branches + +1. **Release workflow** + - Create branch from `develop`: `release/` + - After testing, squash merge to `main` + - Then squash merge back to `develop` + +## Exceptions + +### When to Use Merge Commits + +In rare cases, merge commits may be justified: +- **Feature flags**: When merging a large feature that should be toggled on/off +- **Historical preservation**: When commit history is valuable for review +- **Team decision**: Maintainers may approve merge commits for specific PRs + +To allow a merge commit (temporarily): +1. Comment on the PR requesting merge commit method +2. Maintainer changes merge method in GitHub UI +3. After merge, restore default to squash merge + +### Security Fixes + +For urgent security fixes: +- Maintainer may bypass normal PR process +- Direct push to protected branch with admin override +- Document in PR with `fix(security):` prefix + +## Branch Cleanup + +- **Auto-delete**: Head branches are automatically deleted after merge +- **Manual cleanup**: Delete stale feature branches older than 30 days +- **Protected branches**: Never delete `main` or `develop` + +## Integration with Branch Protection + +This merge strategy works with the branch protection rules defined in `.github/branch-protection.md`: + +- Squash merge + branch up-to-date = clean linear history +- Required approvals + CI checks = quality assurance +- Issue reference + conversation resolution = traceability + +## Verification + +To verify merge settings are correct: + +```bash +# Check recent commits on main - should be one per PR +git log --oneline main | head -20 + +# Verify no merge commits +git log --merges main +# Should return empty (no output) +``` + +## Enforcement + +- **GitHub settings**: Configure merge method in repository settings +- **PR template**: Reminds contributors of commit message format +- **Pre-commit hooks**: Validate commit message format (optional, can be added) +- **CI**: No automated enforcement of merge method (enforced by GitHub settings) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 56b70e90..e2084d93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,8 @@ This guide provides comprehensive instructions for implementing WCAG 2.1 AA comp - `fix/` - `chore/` +For merge strategy and commit message conventions, see [Merge Strategy Policy](.github/merge-strategy.md). + ## Assignment required Before opening a PR, ensure the issue is assigned to you. diff --git a/README.md b/README.md index 3d0d32f1..1e136cd5 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,8 @@ offline mode, redirect management, GraphQL subscriptions, security, and runbooks See [CONTRIBUTING.md](CONTRIBUTING.md) and the workflow notes in [`docs/BRANCH_AND_PR_GUIDE.md`](docs/BRANCH_AND_PR_GUIDE.md). +For merge strategy and commit conventions, see [Merge Strategy Policy](.github/merge-strategy.md). + ## License See the repository's license file.