Submitting and Reviewing Pull Requests

Submitting a pull request (PR) is one of the most important aspects of contributing to an open-source project. A well-crafted PR makes it easier for maintainers to review your work, ensures efficient collaboration, and increases the chances of your code being merged quickly. This article will walk you through best practices for submitting PRs and reviewing them effectively.

What is a Pull Request?

A pull request is a GitHub feature that allows contributors to propose changes to a repository. It enables maintainers to review, discuss, and approve or request changes before the code is merged into the main branch.

How to Submit a Pull Request

Step 1: Prepare Your Code

Before submitting your PR:

1. Complete Your Work: Ensure the issue you’re addressing is fully resolved or the feature is completely implemented.
2. Test Your Code: Run all tests and validate that your changes don’t break existing functionality.
3. Write Documentation: If your PR introduces new functionality, update the relevant documentation (README, user guides, etc.).

Step 2: Commit Your Changes

Your commits should tell a clear story of the changes you’ve made.

• Use Atomic Commits: Each commit should represent a single, logical change.
• bash
# Good
git commit -m "Fix: Resolve off-by-one error in grade calculation"
git commit -m "Feat: Add analytics dashboard for student grades"

# Bad
git commit -m "Fix and update"


• Write Clear Commit Messages:
• Use a consistent format, such as:
• • Type: feat, fix, docs, test, refactor, etc.
  • Short Description: A concise summary of your changes.
  • Optional Details: Add context or related issue numbers if needed.
• Example:
• bash
git commit -m "Feat: Add support for multi-language user interface (#123)"



Step 3: Push Your Code to GitHub

Push your changes to your forked repository:

bash
git push origin branch-name



Step 4: Create a Pull Request

1. Navigate to the Original Repository:
2. Go to the repository where you want to propose your changes.
3. Click ‘New Pull Request’: Select the branch you’ve worked on as the source and the repository’s main branch as the target.

1. Fill Out the Pull Request Form:
   • Title: Write a concise and descriptive title.
     • Example: Feat: Add support for importing student data from CSV files.
   • Description: Clearly explain what your PR does and why it’s needed. Include:
     • A summary of the changes.
     • A link to the issue your PR addresses (if applicable).
     • Any screenshots or logs demonstrating your changes.
     • Notes on tests you’ve added or updated.
2. Submit the Pull Request:
3. After completing the form, click "Create Pull Request" to submit it for review.

Best Practices for Submitting Pull Requests

1. Be Specific: Avoid vague titles or descriptions.
   • Good: Fix: Resolve crash on empty student list in analytics module.
   • Bad: Bugfix.
2. Follow Project Standards: Adhere to coding style guides, commit message formats, and PR templates provided by the project.
3. Keep PRs Small and Focused: Limit PRs to a single feature, fix, or improvement to simplify reviews.
4. Add Context: Include relevant details to help reviewers understand your changes.
5. Use Draft Pull Requests: If your work isn’t complete but you want feedback, submit a draft PR and mark it as "Ready for Review" when done.

Responding to Pull Request Feedback

Step 1: Read and Understand the Feedback

Review all comments carefully. If anything is unclear, politely ask for clarification.

Step 2: Make Changes

Incorporate the suggested changes into your code and commit them. Use descriptive commit messages for the updates:

bash
git commit -m "Fix: Adjust CSS for responsive design as suggested"



Step 3: Acknowledge Feedback

Thank reviewers for their time and input. Acknowledge resolved comments and explain any disagreements constructively.

Code Reviews: Reviewing Pull Requests

If you’re reviewing a PR submitted by another contributor, follow these steps:

Step 1: Understand the Scope

• Read the PR title and description to understand the changes.
• Check the linked issue (if applicable) to see what the PR is trying to solve.

Step 2: Review the Code

• Look for clarity, readability, and adherence to coding standards.
• Verify that the code solves the problem or implements the feature as described.

Step 3: Run the Code

• Test the changes locally (if possible). Ensure they work as intended and don’t break existing functionality.

Step 4: Leave Constructive Feedback

• Be respectful and specific when pointing out issues.
• Highlight positive aspects of the contribution to encourage the contributor.
• Use GitHub’s review tools to suggest changes directly in the code.

Step 5: Approve or Request Changes

• Approve: If the code meets standards and works as intended, approve the PR.
• Request Changes: If there are issues, provide actionable feedback for improvement.

Common Challenges with Pull Requests and How to Overcome Them

1. Merge Conflicts:
   • Cause: Conflicts occur when multiple contributors modify the same part of the code.
   • Solution: Fetch the latest changes from the main branch and resolve conflicts locally:
   • bash
git fetch upstream
git merge upstream/main


2. Unclear Descriptions:
   • Cause: Vague or incomplete PR descriptions.
   • Solution: Use the project’s PR template and provide as much context as possible.
3. Stale Branches:
   • Cause: Working on an outdated branch.
   • Solution: Regularly fetch and merge the latest changes from the repository’s main branch.

Tools to Improve Pull Request Quality

1. Code Linters: Automatically detect and fix style issues (e.g., flake8, ESLint).
2. Continuous Integration (CI): Ensure your PR passes automated tests (e.g., GitHub Actions, Travis CI).
3. GitHub Review Tools: Use inline comments and suggestions for efficient feedback.

Conclusion

Pull requests are the foundation of open-source collaboration. By submitting well-crafted PRs and providing constructive reviews, you contribute to the growth and sustainability of Reality AI Lab projects. A thoughtful PR process ensures better code quality, smoother integration, and a more collaborative environment for all contributors.

Ready to submit your PR? Head over to our GitHub repositories and start collaborating today!

‍