Forks & Pull Requests
Forks
“Forks” are just clones hosted on GitHub, essentially.
We have described the “branch-merge” technique already (in the Git section) for keeping multiple contributors from stomping on each other’s work. That technique works very well when everyone who is contributing has permissions to contribute to the repository. However, for any number of reasons, constantly adding users as “contributors” (i.e., giving them permissions to write to the repository) may not be the most desirable thing to do.
The main reason for this is that all users who have write permissions to the repository can directly push their changes to the repository. And, as a good practice, all new changes to a repository should be vetted (i.e., reviewed) by a trusted contributor. You can do this with branches and merges using GitHub’s “Pull Request” capability, but even then a full-fledged contributor can just merge their changes without review. (Though you can set up your repository settings to require at least 1 reviewer before code is merged. We won’t go into that detail here.)
Another reason for this is because maintaining an up-to-date list of contributors to your code can be annoying.
And a third reason is because you don’t have to!
Why? Because of the “Fork” / “Pull Request” mechanism in GitHub.
Step 1
Let’s create our first fork by heading to this repository:
https://github.com/ncar-hackathons/forkme
And click the “Fork” button at the top-right of the page. Then, select where you want to place your new Fork (your personal space, for example). Now, you should (after a short while thinking) be on the home page of your new forked repository.
Step 2
Now, let’s use the “Create new file” button on the fork repository’s home page to create a new file. Name the file the same as your Cheyenne (or GitHub) username. Then, write your full name in the newly create file and commit this new file to your fork.
Pull Requests
Now that you have added a change to your fork, you can request that the owners of the original repository accept your new changes by clicking on the “New pull request” button.
You should see a page like this:
Below the “Comparing changes” title, you can see that we are going to request that the master branch of our fork (username/forkme) be merged into the master branch of the main repository (ncar-hackathons/forkme). Click the “Create pull request” button to actually put in the request. (You will need to generate a title for this pull request, and possibly a description of what you are proposing, and then click “Create pull request” again.)
Notice that after doing this, we are now at the main repository’s “Pull Requests” page for the pull request that we just created. There are a lot of things you can do here, such as click the “Files changed” tab to see what changes are actually going to be merged in (if this PR is accepted). Or, in the “Conversation” tab, you can have a discussion about the changes that are being proposed. Anyone with write permissions to the main repository can merge your changes into the repository. Though, they may ask you to make additional changes for any number of reasons.
To do this, all you need to do is make new commits to your fork. As long as the PR exists (and hasn’t been merged, yet), any changes you make to your fork will be added (automatically) to your PR.
Once you have satisfied all of the requirements of the owner of the main repository, it will (should) be merged in. And then you can delete your fork (just like you delete your merged branch).