Pull Requests

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 GitHub ¹ if 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.git
```
Your clone will also “know” where it came from.

That finishes setup. You can check that all is well by running

git remote -vv

and 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)

origin is an alias for the location of the repository you cloned. And upstream is 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-improvement
```
The 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 diff
```
to 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 status
```
to 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 status before and after. To stage a new file,
```
git add xsl/pretext-esoteric-format.xsl
```
You do exactly the same thing for existing files you have changed. Run git status before and after.
```
git add xsl/pretext-common.xsl xsl/pretext-latex.xsl
```
Runnning git status should 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 --cached
```
If you need to edit some more, go ahead, and be sure to add your 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 status should show something of a clean slate. You can also run
```
git show-branch
```
to 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-improvement branch. 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.

Cleaning Up.

At any time after pushing your branch to your clone you can/should switch to the default branch (dev now, but changing to master later).
```
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-improvement
```
The 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 upstream.
```
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 dev
```
Now all three repositories (clone, fork, official) look the same and have your contribution. Before your next contribution you will want to pull from upstream into your clone, and then push that into origin (your fork).

Prev Top Next