Ramblers Documentation

Training for Webmasters

Coding 7: How to Initiate a Pull Request

How to Initiate a Pull Request

A pull request (PR) is how you propose your changes to be merged into the main codebase. It's a crucial part of the collaborative development process, allowing maintainers and other contributors to review your code before it's integrated. This guide will walk you through creating a pull request for the ra-tools project.

What is a Pull Request?

A pull request is a formal request to merge changes from your branch into another branch (typically main). It provides:

  • Code Review: Others can review your changes and provide feedback
  • Discussion: A place to discuss implementation details
  • Quality Control: Ensures changes meet project standards
  • Documentation: Creates a record of what changed and why

Prerequisites

  • Changes committed to a branch
  • Branch pushed to GitHub
  • A clear understanding of what your changes accomplish

Pre-Pull Request Checklist

Before creating a pull request, ensure:

  • ☐ All changes are committed
  • ☐ Code has been tested locally
  • ☐ No debug code or console.log statements remain
  • ☐ Code follows the project's style guidelines
  • ☐ Branch is up to date with main branch
  • ☐ All tests pass (if applicable)
  • ☐ Documentation is updated (if needed)

Creating a Pull Request on GitHub

Step 1: Navigate to the repository on GitHub

Go to: https://github.com/CharlieBigley/ra-tools

Step 2: Find the "Compare & pull request" button

After pushing your branch, GitHub typically shows a yellow banner at the top of the page with a "Compare & pull request" button. Click it.

If you don't see the banner:

  1. Click the "Pull requests" tab
  2. Click the green "New pull request" button
  3. Select your branch from the "compare" dropdown

Step 3: Select the base and compare branches

  • Base branch: The branch you want to merge INTO (usually main)
  • Compare branch: Your feature branch with the changes

Ensure the arrow points from your branch to the base branch:

base: main ← compare: feature/my-feature

Step 4: Review the changes

Scroll down to see the diff of all changes included in the pull request. This shows:

  • Files changed
  • Lines added (in green)
  • Lines removed (in red)

Make sure only intended changes are included.

Step 5: Write a descriptive title

The title should clearly summarize what the PR does.

Good Examples:

  • "Add CSV export functionality to reports"
  • "Fix login validation error for special characters"
  • "Update user profile page layout"
  • "Refactor database connection handling"

Bad Examples:

  • "Updates"
  • "Fix bug"
  • "Changes"
  • "WIP"

Step 6: Write a detailed description

The description should explain:

  • What: What changes were made?
  • Why: Why were these changes necessary?
  • How: How do the changes work?
  • Testing: How were the changes tested?

Pull Request Description Template

Template:
## Description
Brief summary of the changes.

## Motivation
Why are these changes needed? What problem do they solve?

## Changes Made
- Added export to CSV functionality
- Updated export controller to handle different formats
- Added new CSS styles for export page

## Testing
- Tested CSV export with sample data
- Verified format compatibility with Excel
- Tested on multiple browsers

## Screenshots (if applicable)
![Export page screenshot](url-to-image)

## Related Issues
Fixes #123
Related to #456

Step 7: Link related issues

If your PR addresses an issue, reference it in the description:

  • Fixes #123 - Automatically closes issue #123 when the PR is merged
  • Closes #123 - Same as "Fixes"
  • Resolves #123 - Same as "Fixes"
  • Related to #456 - Links to the issue without closing it

Step 8: Assign reviewers (if applicable)

If you know who should review your code:

  1. Click "Reviewers" on the right sidebar
  2. Select the appropriate reviewers
  3. They'll be notified of your pull request

Step 9: Add labels (if applicable)

Labels help categorize pull requests:

  • enhancement - New features
  • bug - Bug fixes
  • documentation - Documentation changes
  • refactor - Code refactoring

Step 10: Create the pull request

When everything looks good, click the green "Create pull request" button.

After Creating the Pull Request

Step 11: Monitor for feedback

Watch for:

  • Comments from reviewers
  • Automated test results (CI/CD)
  • Merge conflicts
  • Requested changes

You'll receive email notifications for activity on your PR.

Step 12: Respond to feedback

If reviewers request changes:

  1. Make the requested changes in your local branch
  2. Commit the changes: git commit -m "Address review feedback"
  3. Push to GitHub: git push
  4. The PR will automatically update with your new commits
Tip: Respond to reviewer comments even if you make the requested changes. A simple "Done" or "Fixed in commit abc1234" helps reviewers track the conversation.

Step 13: Request re-review

After addressing feedback:

  1. Click the circular arrow icon next to the reviewer's name
  2. This notifies them that you've made changes
  3. They can review the updates

Handling Merge Conflicts

If your PR has merge conflicts:

This means changes in the base branch conflict with your changes.

Resolution: Update your branch with the latest main

# From your feature branch
git checkout feature/my-feature

# Fetch latest changes
git fetch origin

# Merge main into your branch
git merge origin/main

# Or rebase (alternative approach)
git rebase origin/main

# Resolve any conflicts, then:
git add .
git commit -m "Resolve merge conflicts"
git push

Draft Pull Requests

Using Draft PRs:

If your work isn't ready for review but you want to share progress:

  1. Click the dropdown arrow next to "Create pull request"
  2. Select "Create draft pull request"
  3. This signals the PR isn't ready for merging
  4. When ready, click "Ready for review"

Pull Request Best Practices

Guidelines:
  • Keep PRs focused: One feature or fix per PR
  • Small and reviewable: Aim for PRs under 400 lines of changes
  • Clear communication: Write descriptive titles and descriptions
  • Be responsive: Address feedback promptly
  • Test thoroughly: Ensure your changes work before creating the PR
  • Stay professional: Be courteous in discussions
  • Update regularly: Keep your branch up to date with main

What Happens Next?

After creating your pull request:

  1. Review: Maintainers will review your code
  2. Discussion: There may be questions or suggestions
  3. Revision: You may need to make changes
  4. Approval: Reviewers approve when satisfied
  5. Merge: A maintainer merges your PR into the main branch
  6. Cleanup: You can delete your feature branch

Viewing Your Pull Requests

To see all your pull requests:

  1. Go to the repository on GitHub
  2. Click the "Pull requests" tab
  3. Filter by author: is:pr author:@me

Closing a Pull Request

If you need to close a PR without merging:

  1. Open the pull request
  2. Scroll to the bottom
  3. Click "Close pull request"
  4. Optionally add a comment explaining why

Congratulations!

You've learned how to create and manage pull requests! This is a key skill in collaborative software development. Your contributions to the ra-tools project are valuable and appreciated.

Remember: Every contributor was once a beginner. Don't be afraid to ask questions, and welcome feedback as an opportunity to learn and improve your skills.

Additional Resources