Social Coding in the Underground
Welcome to the Underground! We are a secret organisation planning world domination. This involves a lot of planning, which means we need to know all the best cafes, bars and restaurants around the globe. After all, nobody wants to take over the world on an empty stomach.
The Underground is organised like this:
- The Grand Oligarchy: The OTS organisers. Supreme Leaders of the Underground. The Grand Oligarchs have full control of the organisational effort.
- The Coaches. Learned they are in the ways of Social Coding. They encourage the efforts of the students, and can communicate directly with the Oligarchy.
- The Students. New initiates to the Underground. Yet to fully immerse themselves in the wonders of social coding, beholden to their coaches.
The Underground is in crisis! The most honourable Grand Oligarchs have declared that we do not have enough cafes, bars or restaurants in our repository. Our planning efforts depend heavily on having enough food, caffeine and alcohol. Without places to hang out the organisation will wither away, as students, coaches and even the Oligarchy themselves spend more and more of their time at home, browsing cat pictures on the Internet.
Your mission is to add to our database of bars, restaurants and cafes. The goal is to get your changes into the master repository OpenTechSchool/underground. However, the Oligarchs do not accept changes from just anybody. The Oligarchs will only accept pull requests from one of their trusted lieutenants, the Coaches.
Find your coach
To contribute some code, first you’ll need to find a coach. There are a few ways to do this:
- Sequester one in a non-violent, friendly way, and ask nicely.
- Check the “Forks” on the
OpenTechSchool/undergroundrepository. There will be coaches on there.
- Kindly ask one of your friendly co-students for some assistance.
Your coach will have an
underground repository of their very
own. This is the one you’ll need to contribute to. Then the coach will
forward your changes, and the changes of others, to the Oligarchs’
There are two methods to contributing on GitHub. The first and most
direct is for the owner to grant
push access to you. This allows you
clone their repository directly and push changes without requiring
their approval. Very convenient, but also a security nightmare and a
real hassle to add and remove people from the list.
What sets GitHub apart is their second method of contribution: forking. When you fork someone’s repository, you get a complete copy of their repository under your name. Then you are free to make any changes you want, it’s your code (well, except for the copyright). Your Git repository is exactly the same as theirs. The only difference in GitHub is that your repository will be shown as “forked from” theirs, so people know what the “real” repository is (but we all know that yours is so much better).
So what you are going to do is fork the repository of your coach. DO NOT FORK THE OPENTECHSCHOOL REPOSITORY DIRECTLY! You can click the Fork button on the GitHub page for your coach.
Adding content in Markdown format
To add a new bar, club or restaurant we use a file format called Markdown (extension .md). Think of it as a simpler version of HTML. It allows you to write rich text in a simple text file and have it be readable in both a text editor and a web browser. In GitHub you can use Markdown in pull requests, comments, issues, wiki pages, gists and almost everywhere you write text. In fact, even this course material is written in Markdown, and hosted directly from the course GitHub repository. It’s simplicity and ubiquity make it well worth learning.
In HTML, you might write something like this:
<h1>This is a large heading</h1> <p>This is a paragraph with <em>emphasis</em> and <strong>strong</strong> text.</p>
In Markdown this is much simpler:
# This is a large heading This is a paragraph with *emphasis* and **strong** text.
You will end up with:
This is a large heading
This is a paragraph with emphasis and strong text.
One caveat is that you need to put a blank line between paragraphs. Otherwise it will just lump all your text together.
Think Globally, Commit Locally
Because the Underground is a global organisation, there are directories in its repository for each city it is active in. Add your contributions locally under your city’s directory!
Commit and Push
After you’ve made your contributions locally, it’s time to get them to the coach. We’ll do this by (1) pushing to your repository on GitHub, then (2) submit a pull request to your coach, (3) kindly asking them to accept your changes into their GitHub repository. Your coach will eventually do the same thing, submitting a pull request to the Oligarchy.
Use the same method as before to
commit to your local
push to your repository on GitHub. Now you should
be able to see your changes on your repositories GitHub page.
Time to create a pull request! Open your browser and navigate to
underground repository. There you can see the “Pull
Request” button up the top. Click it, and GitHub will start the Pull
A pull request is a GitHub way of saying “I made some changes and I think you should add them to your repository”. It allows developers to share changes entirely within the website. If the developer on the other end accepts your pull request then GitHub will copy your changes over to their repository and merge them automatically.
If you see “Oops! master is already up-to-date..” then it probably
means that you still need to
push your local changes to GitHub.
Otherwise, make sure your coach is on the left and your repository is
on the right. Then fill out a friendly comment and click
Now your coach will shortly receive a pull request notification.
It’s best practice to add funny pictures as comments to a pull request. And by best practice, we mean not really best practice. But it is fun, and it shows how to use Markdown in comments.
Add a comment to your pull request using Markdown. The format for adding an image is:
![image alt text](http://example.com/url-to-funny-pic.jpg "image title text")
The “image alt text” is the text that is displayed when the image fails to load, or if the person is using a screen reader (yes, there are blind programmers!). The “image title text” is displayed when you hover over the image. For example:
![A pondering cat](http://i.qkme.me/3rgytr.jpg "A cat, wearing a business suit, is sitting a table with a newspaper in hand. Looking up, the cat ponders: 'I should buy GitHub'.")
Always make sure your title text is informative and witty. That way you will garner more chuckles out of those who happen to purview it.
Congratulations on making it this far! You’re almost there!
There is one more thing left to do: keeping up to date with
upstream. In Git upstream refers to some remote repository that you
consider higher or more authoritative than yours. At the moment your
local repository has one upstream repository, your GitHub
repository. When you type
git pull, that’s where it pulls from.
In this case you might consider your coach as also being upstream, or even the oligarchs (aka OTS Organisers) at the top. If they push any changes to their repository, then you’ll want to be able to pull those changes into your repository. For all you know, your coach might have completely overwritten all your changes and added a curse for your pets in the README file. Let’s add another upstream to see what is happening:
$ git remote add upstream https://github.com/OpenTechSchool/underground.git
This adds an upstream repository called
upstream. Now we can
fetch directly from the Oligarchs. This will download the
OpenTechSchool/underground repository and store it under
upstream, so it won’t interfere with your changes:
$ git fetch upstream
If you want to bring the changes into your work, use
$ git merge upstream/master
You might want to have a look at the changes it brought, by typing :
$ git log
This lists all the commits from the most recent one.
git log has lots of options, but you might find it more entertaining
not learning them and use the ugly but very informative:
Now bear in mind, your GitHub repository doesn’t know about these
changes yet, so you’ll need to
push to get it up-to-date:
$ git push
And that’s it! You’re done!