Add a merge strategy policy for TeachLink Web

[Menjay7]

[DOCUMENTATION] Add a Merge Strategy Policy for TeachLink Web

Summary

Establish a consistent merge strategy policy for TeachLink Web to standardize how pull requests are reviewed, approved, and merged. The policy will improve commit history, reduce integration issues, and ensure changes meet repository quality requirements before entering the target branch.

Objectives

• Define the approved merge strategy for pull requests.
• Establish consistent requirements for pull request reviews and approvals.
• Prevent unauthorized or premature merges.
• Ensure required CI checks pass before merging.
• Maintain a clean, traceable Git history.
• Document exceptions and enforcement requirements.

Proposed Policy

1. Approved Merge Strategy

• Use Squash and Merge as the default merge strategy.
• Combine each pull request's commits into a single commit on the target branch.
• Require meaningful, descriptive commit messages that summarize the changes.
• Preserve the pull request title and reference in the resulting commit where appropriate.

2. Pull Request Requirements

Before a pull request can be merged:

• The pull request has a clear description of its purpose and scope.
• All required CI checks pass.
• Required code reviews and approvals are complete.
• Requested changes have been addressed.
• Merge conflicts are resolved.
• Relevant automated tests pass.
• Required documentation is updated.

3. Branch Protection

Configure repository rules to enforce the policy:

• Require pull requests for protected branches.
• Require the configured number of approving reviews.
• Require status checks to pass before merging.
• Require branches to be up to date when appropriate.
• Restrict direct pushes to protected branches.
• Apply restrictions to administrators where supported and appropriate.

4. Exceptions

Exceptions to the default merge strategy should be limited to cases where preserving individual commits or merge topology is necessary.

Any exception must:

• Have a clear technical justification.
• Be approved by an authorized maintainer.
• Follow the repository's existing access-control rules.
• Preserve all applicable review and CI requirements.

5. Documentation and Enforcement

• Add the merge strategy policy to the repository documentation.
• Identify the protected branches to which the policy applies.
• Document the responsibilities of contributors and maintainers.
• Align repository settings with the documented policy.
• Review the policy periodically as the project evolves.

Acceptance Criteria

• The approved merge strategy is documented.
• Pull request review and CI requirements are clearly defined.
• Branch protection expectations are documented.
• Exception handling is explicitly defined.
• Contributors and maintainers have clear merging instructions.
• Documentation matches the repository's actual merge configuration, or outstanding configuration changes are identified.
• Existing contribution workflows remain documented and usable.

Testing and Verification

• Verify the policy documentation is accurate and accessible.
• Review repository settings to confirm the supported merge methods.
• Confirm protected-branch rules enforce the required checks where configured.
• Validate the documented workflow against a test pull request when practical.
• Ensure the policy does not conflict with existing contribution guidelines.

Definition of Done

• The merge strategy policy is committed to the repository.
• Relevant contribution documentation is updated.
• Required repository configuration changes are identified and applied by an authorized maintainer.
• Documentation and configuration are consistent.
• No unrelated application code changes are introduced.
  Close Add a merge strategy policy for TeachLink Web #1739

[drips-wave]

@Menjay7 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]

Thank you for contributing to the project.