Creating Pull Requests: Proposing Changes in Git & GitHub

Previously in this course, we covered introduction-to-forking-master-open-source-collaboration and learned how to syncing-your-fork-how-to-manage-upstream-changes-in-git. Now that you have a synchronized fork, it’s time to move from "owning a copy" to "contributing to the project." This lesson teaches you how to bundle your changes into a Pull Request (PR), the industry-standard way to request that maintainers review and merge your code.

Understanding the Pull Request Workflow

A Pull Request is more than just a request for a merge; it is a collaboration space. It acts as a dedicated forum for discussion, automated testing, and peer review. When you open a PR, you are telling the maintainer: "I have finished this specific task in my own workspace, and I believe it is ready to become part of the main project."

The workflow follows this logical path:

1. Branching: Isolate your work in a feature branch.
2. Committing: Save your changes locally.
3. Pushing: Upload your branch to your remote fork.
4. Opening: Submit the PR on GitHub.

Worked Example: From Feature to Pull Request

Let's assume you are working on our shared project. You want to add a new documentation file. Here is the exact sequence of commands to get your work ready for review.

Step 1: Create a feature branch

Never work directly on your main branch. It keeps your history clean and allows you to work on multiple tasks simultaneously.

Bash
# Ensure you are on main and up to date
git checkout main
git pull upstream main

# Create and switch to a new feature branch
git switch -c add-readme-docs

Step 2: Make your changes and commit

Create your file, stage it, and commit. Remember to write a descriptive commit message, as it will appear in the PR history.

Bash
touch README.md
git add README.md
git commit -m "Add initial project README documentation"

Step 3: Push to your fork

Since you are working on a fork, the origin remote points to your GitHub repository. Push your new branch there.

Bash
git push -u origin add-readme-docs

Step 4: Open the Pull Request

1. Navigate to your fork on GitHub in your web browser.
2. GitHub will detect the new branch and display a yellow banner: "Compare & pull request." Click it.
3. Fill in the title and description. Be specific: explain what you changed and why.
4. Click Create pull request.

Hands-on Exercise

1. Create a Branch: Using the repository you forked in the previous lesson, create a branch named update-config.
2. Make a Change: Create a new dummy file named config.txt and add some text to it.
3. Push: Push this branch to your remote fork (git push -u origin update-config).
4. Open: Go to your repository on GitHub and click the "Compare & pull request" button to submit it.

Common Pitfalls

• Working on Main: A common mistake is committing directly to main. If you do this, your PR will contain all your local commits, making it harder for maintainers to review. Always use creating-branches-how-to-use-git-branch-to-manage-workflows.
• Mixing Concerns: Keep one PR to one feature. If you fix a typo while adding a new feature, do them in separate branches. This keeps the git-squash-and-merge-streamlining-your-pull-request-history process much cleaner for the maintainer.
• Ignoring Feedback: Once a PR is open, be prepared for comments. The goal isn't to get it merged instantly, but to reach the project's quality standard through iteration.

FAQ

Q: Can I keep working on the PR after it's open? A: Yes! Any additional commits you push to that same branch will automatically appear in the open Pull Request.

Q: What if the maintainer asks for changes? A: You don't need to close the PR. Just make the changes locally, commit them to the same branch, and push. The PR updates automatically.

Q: How do I know if my PR is good enough? A: Most professional projects use pull-request-integration-protecting-main-with-ci to run automated tests. If the checks turn green, you're usually in a good spot to request a human review.

Recap

You have now learned to isolate work into branches, push those branches to your GitHub fork, and initiate a Pull Request. This is the fundamental mechanism for all open-source and team-based development. By using this workflow, you ensure that your contributions are clean, trackable, and easy for others to review.

Up next: We will dive into the collaborative side of this process in Reviewing Code, where you'll learn how to handle feedback and communicate effectively during the review cycle.