Submitting a Pull Request

The Pull Request Workflow: From Local Change to Public Proposal

A Pull Request (or PR) is a formal request you send to the maintainers of the upstream repository, asking them to "pull" your changes into their project. It bundles together your commits from a specific branch and presents them in a way that's easy to review, discuss, and merge.

The entire process can be broken down into four main steps, which we'll cover in detail:

1. Branch: Create a new branch on your local machine to isolate your work.
2. Commit: Make your changes and commit them with a clear message.
3. Push: Push your new branch and its commits to your fork on GitHub (origin).
4. Pull Request: Open a pull request from your fork to the original upstream repository.

Let's walk through this process together.

Step 1: Create a Branch for Your Changes

As we've discussed, it's a critical best practice to do all your work on a dedicated branch, not on main. This keeps your main branch clean and in sync with the upstream project, and it allows you to work on multiple contributions at once.

Since you have a background in software development, you can think of this as creating a feature branch for every distinct task or bug fix. The rule is simple: one branch, one pull request.

Let's see this in action.

To create a new branch and switch to it, you use the command:

git checkout -b new-feature-branch

Replace new-feature-branch with a short, descriptive name for your change (e.g., fix-readme-typo, add-user-authentication).

Step 2: Commit Your Changes

Once you're on your new branch, make your desired changes using your favorite code editor. This could be fixing a bug, adding a new feature, or improving documentation.

After you've made your changes, stage and commit them. We covered writing good commit messages in a previous lesson, and this is where that skill comes into play.

# See what files you've changed
git status

# Add the files you want to include in the commit
git add .

# Commit your staged changes with a descriptive message
git commit -m "docs: Fix typo in the installation instructions"

Step 3: Push Your Branch to Your Fork (origin)

Your new branch and commit currently exist only on your local machine. To create a pull request, you first need to get them onto GitHub. You'll do this by pushing the branch to your fork, which Git knows as origin.

The command to push your new branch is:

git push origin new-feature-branch

This tells Git: "Push my new-feature-branch to the remote named origin."

Step 4: Create the Pull Request

This is the final and most rewarding step. Once you've pushed your branch to your fork on GitHub, you can ask the original project to merge your work.

You will find a comprehensive guide for this process in the "Making a pull request to an open-source project" document. It includes helpful tips and context.

Let's watch the final demonstration of this process.

Here's a breakdown of the process on GitHub:

1. Navigate to the upstream repository. After you push your branch, GitHub will often display a banner on the original project's page with a "Compare & pull request" button. Click it. If you don't see it, go to the "Pull requests" tab and click "New pull request".

2. Verify the branches. This is the most important screen. You need to ensure you're asking to merge the correct branches.

*This is the 'Open a pull request' screen on GitHub. It's where you define the source of your changes (head) and their destination (base).*

*   **Base repository:** This should be the original project (e.g., `project-owner/project-name`).
*   **Base branch:** This is the branch you want your changes to be merged *into*, usually `main` or `master`.
*   **Head repository:** This should be your fork (e.g., `your-username/project-name`).
*   **Compare branch:** This is the branch you just pushed with your changes.

3. Write a clear title and description. Do not underestimate this step. Your PR is a communication tool.
* Title: A concise, one-line summary of the change.
* Description: Explain what you changed and why. If you are fixing a reported bug, link to the issue using the syntax fixes #123. This automatically links the PR to the issue and will even close the issue when the PR is merged.

4. Create the pull request. Once you're satisfied with the title and description, click "Create pull request".

Congratulations! You've just made a contribution proposal. The project maintainers will be notified, and a discussion about your changes can begin.

Your Turn: Practice Makes Perfect

The best way to learn this workflow is to do it. There are several repositories created specifically for people to practice making pull requests.

• The repository used in the LINK reading guide: gabrieldemarmiesse/getting_started_open_source.
• A popular practice repo mentioned by Hitesh Choudhary in his video (LINK): hiteshchoudhary/apihub.
• The classic GitHub practice repo: octocat/Spoon-Knife.

I encourage you to pick one of these, fork it, clone it, create a branch, add your name to a "Contributors" file (or make any other small change), and open a real pull request. It's a low-pressure way to go through the motions.

Conclusion

You now have the complete technical workflow for proposing a change to an open-source project. This process, from forking a repository to creating a pull request, is the universal standard on GitHub and a skill that will serve you in any collaborative project.

Key Takeaways:

• The standard workflow is: Branch -> Commit -> Push -> Pull Request.
• Always work on a dedicated branch for each distinct change.
• You push your feature branch to your fork (origin), not the upstream project.
• A pull request is a request to merge a branch from your fork (head) into a branch in the upstream project (base).
• A clear title and detailed description are crucial for getting your pull request reviewed and merged efficiently.

Preview of the next lesson:
Now that you know how to propose changes, what happens if the original project is updated while you are working on your feature? This can sometimes lead to merge conflicts, where Git can't automatically combine your changes with the project's new code. In our next lesson, you'll learn how to merge branches locally and resolve common merge conflicts, an essential skill for keeping your work in sync with an active project.