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:
> 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
> 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)
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:
If you click the button, you'll be taken to the UI, where you can actually send the PR to me.
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!
The internet has gotten a lot of flak recently for facilitating information pollution via the World Wide Web, which is a shame, since the internet is also an incredible force for good in the world.
I recently realised how much I love looking at what people produce online. It's easy for me to spend lots of time looking at aggregated content on Hacker News and Lobste.rs, in part, because it's rich in stuff that represents the best of the web; highly heterogeneous content from individual creators who are passionate about what they're doing. In particular, Drew De Vault's blog and work is a good example of content I highly value, and Jamie Tanna's post on the indie web helped motivate me to start the blog.
Conveniently, I do a lot of journaling and note taking as it stands; I keep a gratitude journal, a philosophy journal, write notes on lectures and papers for my university studies, and keep track of other random assortments. I hope that the additional effort required to translate the content into a blog and make it accessible to all is low enough that I can post fairly regularly, and enjoy the process.
Here's to blogging!