Creating a pull request

The git push command provided you with a direct URL for creating a pull request. You could also visit the GitHub repository to see a button for creating the pull request.

Pull requests let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch. - GitHub Docs

Visiting the pull request URL takes you to the Open a pull request page in GitHub:

GitHub - Open a pull request

You can view the changed files when you scroll down the page:

GitHub - View changed files

What are good pull requests made of?

When creating a pull request, it helps to think that you are creating it for someone who is not very familiar with the things that the pull request will affect. You want to provide enough context and details to clarify the benefit of merging the pull request changes to the master branch of the project.

  • What is the pull request about? Does it add a new feature, fix an issue, or maybe remove some unnecessary stuff?
  • How can one test it on their computer? It just works? Or maybe you need to set things up manually?
  • Are there some known issues that one needs to take into account?

There's no exact correct level of information you want to provide. It all depends on your project, team, and complexity. Simple changes to simple projects might require less information than larger changes to a huge project.

Pull request description - Take 1

This pull request removes the hard-coded login credentials from the robot to a vault for better security.

Is that enough? Well, not quite in this case. The purpose is clear, yes. It makes sense. But one can not just checkout this branch and run it since there is the requirement for setting up the vault file. Let's add some information.

Pull request description - Take 2

To test this, create a vault.json file in your home directory (/Users/<your-username>). Paste the following JSON and update the value for the username and the password properties:

{ "robotsparebin": { "username": "username-here", "password": "password-here" } }

Update the path to the vault.json file in the devdata/json file.

Looks better! Now there are instructions on making the thing run. Click the Preview tab to preview the description:

GitHub - Preview the pull request description

Click Create pull request. You will see the Pull requests link in the top navigation updates to show there is one open pull request:

GitHub - Pull requests link

Clicking on the Pull requests link takes you to a listing of all open pull requests:

GitHub - Pull requests listing

Notice that we did not edit the title of the pull request. In this case, the first commit message is used as the name. You can always go and edit the title if it is not descriptive enough!

Pull request, merge request. Potayto, potahto.

Trivia: GitHub uses "pull request". GitLab uses merge request. Same same, but different.

What we learned

  • Pull requests are for reviewing and discussing proposed concrete changes to your project.
  • Pull requests are a way to verify/improve/modify changes before merging them into the master branch.
  • The pull request description should provide enough information so that someone can verify and test the changes.