Section 52.5 Pull Requests
Contributions to the code repository are accomplished with a pull request. The short version is that you have a copy of the repository and you make a collection of changes on your copy. Then you make a request to have your changes “pulled into” the official (main, canonical) repository. A pull request is a concept independent of GitHub, but one of GitHub’s advantages is that it makes a pull request very easy to create and manage.
One-Time Initial Setup.
- Make an account on GitHubif you do not have one already. A username that bears some correspondence to your real name or favorite email name is helpful.
- Log into your (new) account.
- Go to the official repository for PreTeXt. Find a button labeled
Fork, roughly in the upper-right corner. Click on it. This will make a copy (a fork) of the official repository in your GitHub account. This repository is called a fork since you are going to make improvements there and your version will diverge from the official version. The fork will “know” where it came from.
- Install a command-line version of Git on your local computer. Heed the advice above about using front-ends.
- You are now going to make a local copy of your fork. Think of it as a mirror—you will do your best to keep the copy and the fork in-sync. Git calls this a clone. In your fork (i.e. in your account, find a green button partway down the right side. Clicking on it will bring up a textbox with a URL you can copy. Now at the command-line, execute something similar to
git clone https://github.com/mjsmith/mathbook.gitYour clone will also “know” where it came from.
- That finishes setup. You can check that all is well by running
git remote -vvand the response should be something like
origin https://github.com/mjsmith/mathbook.git (fetch) origin https://github.com/mjsmith/mathbook.git (push) upstream https://github.com/PreTeXtBook/pretext.git (fetch) upstream https://github.com/PreTeXtBook/pretext.git (push)
originis an alias for the location of the repository you cloned. And
upstreamis an alias the fork uses to know the location of the official repository.
Preparing Your Changes.
The following all happens on your local computer, using your clone, at the command-line.
- Create a branch for your work, and switch into it.
git checkout -b my-big-improvementThe name you choose will not ever be part of the official repository, but it will be part of the record on GitHub. So you do not have to be too careful, but it should be informative.
- Use a text editor to make changes to existing files, or to create and populate new ones. As you save the affected files, you can type
git diffto see the changes to existing files. See the rest of this guide for particulars about the code.
When finished, you will package up your changes as a commit, the fundamental unit of a git repository. Throughout this process (and at any other time), you can type
git statusto see how your repository is changing.If you have created new files, you need to stage them. You can see these files’ status changing if you run
git statusbefore and after. To stage a new file,
git add xsl/pretext-esoteric-format.xslYou do exactly the same thing for existing files you have changed. Run
git statusbefore and after.
git add xsl/pretext-common.xsl xsl/pretext-latex.xslRunnning
git statusshould now show that all affected files (changed, new) are now in the staging area, and no files with changes are left behind. You can preview the commit with
git diff --cachedIf you need to edit some more, go ahead, and be sure to
addyour new changes into the staging area. Now you are ready to make your commit.
git commit -m "Create a new conversion to an esoteric format"Now
git statusshould show something of a clean slate. You can also run
git show-branchto get a pictorial version of your branch.
Creating the Pull Request.
Now you will communicate your changes (on a branch on your local computer) to GitHub as a request for incorporation into the official repository.
- First, push your branch to your fork on GitHub. Recall that this repository is known as
origin. On your local computer, at the command-line,
git push origin my-big-improvement
- Now move to your web browser and your fork on GitHub, which now has a copy of the
my-big-improvementbranch. You should see a prominent message about your new branch, and a green button labeled
Compare & pull request. Click on it.
Now you have a screen titled “Open a pull request”, where you can describe the purpose of the new code. Then click on the green button labeled
Create pull request.That’s it. The developers responsible for approving pull requests will be notified automatically and receive your code in a way they can test and review it in their own forks/clones of the repositories. You can see the pull request in action at the appropriate area of the official repository. Pretty slick.
Pull Request Verification.
It is often advisable to add an example of any new markup, new situation, or bug-provoking content into the sample article as part of a pull request. Please do so, as appropriate. However, because we do rolling releases, all code gets thoroughly tested. For this reason please put all changes to the sample article, and only changes to the sample article, onto a first commit. Code should then follow on subsequent commits. This makes a big difference in our ability to test quickly and accurately. Thanks. (Ask if you need help rearranging your commits to achieve this, or see Section 52.6.)
Modifications to a Pull Request.
To Do: describe how a pull request might iterate to approval/merge.
- At any time after pushing your branch to your clone you can/should switch to the default branch (
devnow, but changing to
git checkout dev
- Your pull request ends when the lead developers merge your branch into the main branch that everybody uses. The commit will have your name on it, as part of the permanent record. But the commit may have changed slightly between initiating the pull request and its subsequent merge. You will want to remove your original branch from your clone on your local computer.
git checkout dev git branch -d my-big-improvement git branch -D my-big-improvementThe second command will fail, as a safeguard against deleting branches with temporary (but important) work on them. The capital “D” is a “forced deletion” so should be used with care! But it is the right thing to do here, since your work has been incorporated into the official repository.
- But, of course, you want your new improvement like everybody else. So you are now going to pull it from the official repository into your clone on your local computer. Remember that the official repository is known as
git checkout dev git pull upstream dev
- Technically, you could now totally trash your fork (making your clone disconnected), and make a new fork and clone for your next contribution. Instead, you can sync your clone with the fork.
git checkout dev git push origin devNow all three repositories (clone, fork, official) look the same and have your contribution. Before your next contribution you will want to pull from
upstreaminto your clone, and then push that into