On GitHub, a Pull Request (PR) is a crucial way for developers to submit code changes to a project repository. Simply put, when you’ve completed new feature development or bug fixes and want to merge these changes into the project’s main branch (such as main or master), you can do so by opening a PR. PRs allow project maintainers and team members to review your modifications, collectively assess code quality, and ensure the changes are safe and adhere to project standards.

Why Use PRs?¶

1. Code Review: PRs are the core mechanism for team collaboration. Others can review the changes, provide suggestions or feedback, and prevent “buggy” code from being merged directly into the main branch.
2. Historical Record: PRs document the context of all changes (e.g., purpose, test results), making it easier to track and backtrack later.
3. Standardized Collaboration: PR workflows help teams unify coding styles, testing standards, and submission norms, reducing chaos.

Preparing for a PR¶

Before creating a PR, ensure your local code is ready to avoid PR failures due to basic issues. Follow these steps:

1. Commit Local Changes
   Assuming you’ve completed development on your local feature branch (e.g., feature/new-login), commit your changes to the local repository:

   git add .  # Stage all modified files
   git commit -m "Add user login form validation"  # Commit with a clear message

2. Update Your Branch (Resolve Conflicts)
   If the project’s main branch (e.g., main) has new updates (e.g., other developers merged code), sync your branch to ensure it’s up-to-date:

   git checkout main  # Switch to the main branch
   git pull origin main  # Fetch the latest code from the main branch
   git checkout feature/new-login  # Switch back to your feature branch
   git merge main  # Merge the latest main branch changes into your feature branch

If conflicts arise (e.g., the same file was modified by multiple people), resolve them manually and re-commit.

3. Verify Commit Status
   Use git log to check the commit history and ensure all changes are correctly committed and the branch is clean (no uncommitted modifications).

Creating a PR on GitHub¶

Once your local setup is complete, initiate the PR on the GitHub repository page:

1. Access the PR Creation Page
   Open the target repository (e.g., your forked repo or team shared repo), click the “Pull requests” tab at the top, then click the “New pull request” button.

2. Select Branches
   - Base Branch: Choose the target branch to merge into (typically the project’s main branch, e.g., main).
   - Compare Branch: Select the branch with your changes (e.g., feature/new-login).
   GitHub will automatically check for conflicts. If conflicts exist, it will prompt “Can’t create a merge…”, so resolve them locally (refer to the “Update your branch” step above).

3. Fill in PR Details
   After confirming the branches, click “Create pull request” to enter the PR details page and fill in these key fields:
   - Title: Concise and clear, e.g., “Add user login form validation”.
   - Description: Explain the purpose (e.g., “Fix login failure issues reported by users”), implementation (e.g., “Add SMS verification code login”), and test results (e.g., “Tested locally and passed”).
   - Linked Issue: If using Issues to track problems, include “Fixes #123” (replace #123 with the Issue number) to auto-close the Issue upon merging.

Code Review and Feedback¶

After submitting a PR, maintainers or team members will receive notifications and may leave comments (e.g., “Variable name needs clarification” or “Missing unit tests”). Here’s how to handle feedback:

1. Make Code Changes Based on Feedback: Adjust your code locally, then re-commit the modifications:

   git commit -m "Fix review comments"

2. Update the PR: GitHub will automatically refresh the PR page to reflect the latest changes.
3. Reply and Communicate: Respond to each review comment (e.g., “Renamed variable to user_phone”) to ensure clear communication.

Merging a PR¶

Once all review comments are addressed, merge the PR into the target branch. GitHub offers three merging methods; beginners are recommended to use:

1. Squash and merge (Recommended)
   Compresses all PR commits into a single commit, keeping the main branch history clean. Ideal for small changes to avoid cluttered commit records.
   Action: On the PR page, click “Merge pull request”, select “Squash and merge”, then confirm with “Confirm squash and merge”.

2. Rebase and merge
   “Replays” your branch commits on top of the target branch, creating a linear history. Use for complex branches but with caution (may alter commit history).

3. Create a merge commit
   Preserves all commit history by creating a new merge commit. Suitable for large PRs or scenarios requiring full historical records.

Post-Merge Cleanup¶

After merging, perform these steps to keep the repository organized:

1. Delete the Source Branch: On the PR page, click “Delete branch” to remove the merged branch (e.g., feature/new-login) and avoid branch clutter.
2. Sync Your Local Branch: If continuing development, delete your local branch and re-fetch the main branch:

   git checkout main
   git pull origin main
   git branch -d feature/new-login  # Delete the local branch

Common Issues and Best Practices¶

1. Branch Naming: Use descriptive names (e.g., bugfix/login-error) instead of generic names like feature or dev.
2. Commit Messages: Keep commit messages concise and purpose-driven (e.g., “Fix: Fix mobile adaptation issues”).
3. Small, Focused PRs: Aim for PRs that solve one problem (avoid PRs with over 500 lines of code, as they’re harder to review).
4. Conflict Resolution: If conflicts occur during merging, resolve them locally (using git merge or git rebase) before re-submitting.

By following these steps, you can effectively create PRs on GitHub for secure and standardized code collaboration. Remember, PRs are not just a submission process—they’re a critical part of team communication and code quality assurance.