Recent postsRSS

How to make a Pull Request (for my notes)

01.11.2019

If you want to skip to the tutorial, click here.

Soon after starting at university, I started to become frustrated with the rather poor quality of the lecture slides we would have to revise from. Though all the information was there, and it was (mostly) perfectly clear if you attended all the lectures, when it came to revising for the exams, it was hard to figure out what exactly was happening from the lecture slides themselves.

Thus, I started to make my own notes and flashcards, which I put online after each of my courses was finished. To my very pleasant surprise, other students at Manchester started to use them for revision too. This is very visible from the large spikes in traffic that my website receives during every exam period.

The peaks in my website's traffic correspond to exam periods at university.

This makes me really, really happy, but with great happiness comes a little bit of responsibility. Since so many students are using my notes to revise and learn, any mistakes in the notes (and there are likely quite a few) could be propagated onto them, which nobody wants. Furthermore, some of the courses have changed and the material has become out of date, argh!

Since my notes are 100% open source, I've always hoped that they would become living documents, and students would update the notes as they found mistakes, or thought of improvements. While I do typically receive a few changes per year, I think there's a very low ratio of eyes-on-page to proposed-amendments, and I'd like to improve that. I recognise that many students, having just come to university, might not be familiar with LaTeX, or with Git or with how pull requests work, so this is my effort to help students contribute.

So, what follows is my guide on how to submit a pull request to my notes, from start to finish.

I'll split the tutorial into three parts; the structure of my notes repositories, how to edit the notes, and how to submit a PR.

How my notes are structured

As of writing, my bachelor's degree notes are split into three repositories on GitHub, corresponding to each year I spent at university. The repositories can be found here, here and here. In this tutorial, I'll use my first year notes as an example, but the other two repositories are similar.

I'll assume that you have a terminal set up that you can type Git commands into. If you've not heard of version control or Git before, perhaps read this intro before continuing.

If you want to make changes to the notes, the first step is to fork the repository. To do that, you need to open the repository in your web-browser and hit the 'fork' button in the top-right corner. This will create a copy of my repository under your GitHub account, that you can make edits to Eventually, you'll send me a request to pull your edits back into the original repository (and that request, is the pull request).

Once you've forked the repository, you'll need to download it to your machine before you can make any changes. To do that, you should run the following command, but replacing `Todd-Davies' with your username so that you download your copy of the repository:

$ git clone https://github.com/Todd-Davies/first-year-notes.git

Now, if you run cd first-year-notes and then run ls, you'll see the structure of the notes directory:

$ ls
> COMP10120 COMP11212 COMP15111 COMP18112 setup
> COMP11120_1 COMP12111 COMP16121 README.rst
> COMP11120_2 COMP14112 COMP16212 page_count.sh

Each of the COMP* sub-directories contain the source for one of my notes files, and as you can probably guess, they're named after the course code for that course.

Lets see what's inside one of the course subdirectories. I'll cd into one of them, then see what's inside:

$ cd COMP15111
$ ls
> build.sh notes.pdf
> content.tex notes.tex
> drawstack.sty packages.tex
> flashcards rm_extras.sh
> kindle.pdf tcolorbox.sty
> kindle.tex two_box_model_diagram.pdf
> meta.tex two_box_model_diagram.tex

How to make a change, and build the PDF files

That's a lot of files, and most of them aren't relevant for the basics. The most important thing to know, is that the content goes inside the .tex files, and the output is in the .pdf files. The actual notes usually live in the content.tex file. In order to convert the tex files into pdf files, then you need to either run a command called pdflatex, or run the build script that's usually provided (later versions of my notes should use makefiles) ./build.sh.

I'm not going to go into editing the LaTeX code now, because that would make a long post already longer than it is, but to get your feet wet, try making a change to some text, saving the file, compiling the code using the build script, and viewing the updated output in a PDF viewer (your web browser should do the trick).

How to make a change in Git, and push to GitHub

Once you've done that, if you run git status, you should see output similar to the following:

$ git status
On branch master
Your branch is up to date with 'origin/master'.

Changes not staged for commit:
(use "git add (file)..." to update what will be committed)
(use "git checkout -- (file)..." to discard changes in working directory)

modified: content.tex
modified: kindle.pdf
modified: notes.pdf

no changes added to commit (use "git add" and/or "git commit -a")

As Git says, the next step is to make a commit with the files we changed! Lets do that, and then push back up to the repository we forked on Github.

$ git commit -a -m 'My first commit'
...
$ git push origin master
...

Note that most of the courses have a section for contributors; please do add yourself in there if you do some editing, however small!

How to make a Pull Request (PR)

Now, if you go back to the repository you made in GitHub, and click on 'Pull Requests' in the tabs, then you should be able to see a 'New pull request' button on the top right side:

The green button on the top right!

If you click the button, you'll be taken to the UI, where you can actually send the PR to me.

Next steps

Now, I'll get an email that you sent me a PR, and within a few days (hopefully!), I'll take a look and either merge the PR into the codebase (which will automatically make the updated versions of the notes available on my website), or give you some feedback if we should make some changes before we merge.

If you'd like to see examples of previous PR's, then you can look here.

Finally, studying CS is hard, revising is hard, exams are hard, writing LaTeX is hard, putting all the knowledge you've learnt into coherent sentences so that other people can understand it is also... hard. So first off, if you do get around to making a PR, then you have my sincere gratitude for the effort, and second, I promise to be friendly, and will spend the time with you to help with any part of the process if required. If you have any problems, feel free to email me!