If you’ve been following along, you understand why you might want to contribute to open source projects, and you understand the nature of open source communities. You’ve also perhaps found your target open source project.
Now, how do now you contribute to open source on GitHub? We’ll go into that next in this post, which deals with the practical side of things.
Practical – Learn how to use GitHub in the browser to contribute to open source documentation
- Find an open source project
- Look at open issues
- Work out the website structure
- Fork the repository on GitHub
- Write your documentation
- Format in Markdown or similar
- Commit your code to the master branch
- You are an open source contributor!
This guide assumes you already have a GitHub account (the address is www.github.com). If you don’t, make one right now. It’s completely free to use.
A word about coding
If you’re a beginner contributor like me you’ll usually be making changes to a website. It’s possible to make front end changes like text, or fiddle with a bit of HTML or CSS, even if you’re not a developer.
Since I know basic coding, I was able to quickly work out how to make some changes in reStructuredText to add my content to the Write the Docs website.
If you want to make documentation changes (like me), you still need to understand how to navigate a codebase. It’s not quite as simple as “adding some documentation” on GitHub, no matter what people say.
What if I can’t code?
It’s hard for experienced developers to remember how impenetrable code (and GitHub) can be to complete newbies.
You need to understand a website’s structure in order to format, commit and merge your new content on GitHub. Websites are made of code. Otherwise, what are you contributing to?
There’s no getting round the fact that you do need to know some code to contribute to open source projects on GitHub. But not a huge amount of code!
How can I learn to code?
It really doesn’t take that long to learn the basics of HTML and CSS if you’re dedicated. You can find some great free courses on Codecademy.
Front-end coding is different to “programming” the back-end of an application (although the distinction is becoming blurred) and it’s easier to pick up the basics.
Not understanding front-end development might mean you have more to learn before you can contribute to an open source software project. That’s fine – the open source projects will still be there when you’re ready.
I published previous posts on free UK coding groups for women and free HTML learning resources.
Now let’s get to the guide.
1. Find an open source project
Open source projects like FreeCodeCamp, Mozilla’s FireFox web browser, and Atom are so popular they’re overwhelming for brand new contributors.
You should ideally find a project that is proactively welcoming to “first-timers” to practice on. In the workshop I’m co-hosting, we’ll also use a practice repository to help you learn the necessary skills.
You should also try find your own open source project for “real-life” if you can. GitHub has published a guide to finding open source projects.
2. Look at open issues
In GitHub there is a tab on every project called “Issues”. This is a list of updates that the project moderators want to be made to the codebase, such as improvements and bug fixes. It’s anything that will make the software better – including documentation.
You’ve in theory chosen your open source project and you know where the repository (codebase) is on GitHub. Now, you need to go to the repository of the project on GitHub in the browser.
Click on each issue to bring up more information about it.
In the following example we are looking at “Content for “approaches to creating and producing docs”. This means they want a page on their website to tell people how they can write documentation.
When I was at Write the Docs conference, we discussed their open issues in person. The issue I picked for my first contribution was to write new documentation on how to make running Write the Docs meetups more sustainable.
Try to pick a documentation issue that you think you can tackle. This requires an ability to write content, along with basic understanding of codebases – not programming.
It’s not easy to gauge the skill level that any issue will require, but writing documentation is what we’re aiming for right now. Sometimes projects label their issues to help:
On the right hand side, the coloured labels are the tags for the project. This is a good first issue – for developers.
A site called Up for Grabs has a list of open source projects with open source issues tagged according to difficulty. It’s mainly aimed at developers but you might be able to find something that matches your skill level.
3. Work out the website structure
Now you know there is an issue you can work on, click around the project on GitHub to get a sense of how it is organised and what files it contains.
Most websites follow a similar structure. They are organised like files and folders on a computer because that’s all they are really.
Write the Docs is arranged so that all the docs are in a folder called “docs”. You can compare this file system to the live website navigation for a better idea of how it is structured.
There is also a README file in every GitHub repository which contains the instructions for the codebase. In the case of Write the Docs it is called “README.md”. If you scroll down, the contents are automatically displayed on the main page.
The site is deployed using Sphinx static site generator, which is a common tool for documentation sites.
The Write the Docs codebase uses reStructuredText for content. reStructuredText is a type of markup language. It’s a tagging system that can easily convert text into multiple formats. It’s relatively good for moving between platforms and languages, and originates in Python documentation.
You can tell what format a file is written in using by looking at the file extension. In this case, we will be looking at files that end with “.rst”.
4. Fork the repository on GitHub
Fork the repository in the browser to become a contributor. Anyone can fork any public project and it doesn’t make any changes to the code. There’s not etiquette surrounding joining a project and you won’t have to do anything right away.
I found the Write the Docs repository on GitHub [click the link to get to the repository] and “forked” the repository (press the grey button that says “fork”).
GitHub is designed to allow people to work on code in teams by minimising the risk of code “conflicts”. Contributors can fork the repository, and this is called “version control”.
Think of it like the opposite of saving all those different versions of Microsoft Word files to your desktop when trying to work with other people on the same document. You’re essentially creation another (matched) version of the code in your account so you can work on it by yourself.
NOTE: GitHub remembers that your cloned repository is linked to the master branch so that you can easily “merge” your changes back later. You don’t have to do anything special and the code will automatically go back to the moderators when you’re done.
Once you’ve forked your repository, you can play around with making changes, and later you’ll “merge” the code back in.
5. Write your documentation
In a separate step, I wrote the content that I wanted to submit to Write the Docs in my favourite editor,Google Docs. You can use whatever editor you want.
I saved it as a normal file because I was going to copy and paste the text into GitHub later (Google Docs automatically saves).
I followed the structure and style of the existing documentation and tried to be as clear as possible. Some projects may have contribution guidelines that tell you how to write for them.
Writing the documentation took me several hours because I wanted to get it perfect. If you pick a smaller issue it will take you less time.
6. Format in Markdown or similar
When I had finished writing the content, I created a new file in the correct location of the repository by clicking the “create new file” button.
You’ll name your file on the next page that appears:
If you don’t need to create a new page and just need to edit an existing page, click file to open it, and then click on the pencil button to open the editor.
Once you’ve copied your documentation to the clipboard, you can just right-click in the GitHub editor and click “paste without formatting”. This strips away any formatting from the other word processing editor you’ve used.
To make the documentation look pretty, and as I didn’t have existing knowledge of how to write in reStructuredText, I had to improvise. I copied the formatting from their other content.
For example, I could see that headings were designated by a double hash (##). Bullet points were designated by an asterisk (*) at the beginning of each line.
Here’s an example of content written in reStructuredText:
Check the formatting in the “preview” editor inside GitHub and edit it until it looks good.
NOTE: I made the changes directly in the web interface so I didn’t have to download anything. If we were to work with GitHub desktop or Git command line we would need to download the repository.
I checked for typos and errors before finally deciding I was happy with my contribution.
7. Commit your code to The master branch
I saved my changes by committing the code in GitHub. Scroll down to the bottom of the page you’re editing to see the commit box.
A commit in GitHub is a snapshot of your changes to the code, and you want to commit as regularly as possible. It’s a bit like saving your work in Microsoft Word. It’s different from pushing the code back to the “master branch” because it only saves it to your fork.
There is a place to comment on your commit when you save it. Make this comment as descriptive (but brief) as possible so you don’t add any extra work for the moderator. Tell the moderator what you’ve done, why, and what issue you’re addressing.
I chose the option that allowed me to combine my code with the original repository, so I pushed the changes back to master (known as “merging”).
NOTE: If you make complex changes such fixing a bug or updating a feature, you can create a new branch and open a “pull request”, which means you ask the moderator to look at your new code.
With new documentation, it’s pretty much impossible to break the original code. You’re not changing any of the inner workings of the application, which is usually when “merge conflicts” can occur. That’s why we just commit directly to master.
9. You’re an open source contributor!
After a day had passed, the project moderator managed to look at my commit and accepted it into the master code. They were also very happy, and thanked me for my contribution in a comment.
If your contribution isn’t accepted, try to ask how you could make it better. Accept whatever outcome gracefully and try again next time.
Just like that, I became an open source contributor.
Final remarks
My first open source contribution took me a whole day, and required the help of several people along the way. This milestone had been in the making for nearly a year – since I first decided I wanted to contribute to open source.
You can contribute to open source documentation in a relatively straightforward markup language like reStructuredText. It wouldn’t be possible for me to just learn a whole coding language (eg Python) in this way.
If you have less experience with coding, learning to contribute might take you a bit longer.
Try to gain entry to the open source project community at an event or workshop like I did. Friendly people can tell you exactly what contributions they need, and which “issues” would be suitable for your level of technical skill.
You should persist because:
GitHub is technical and practical so you get to understand how stuff works.
Documentation appeals to natural writers who love to help people.
Open source has amazing communities and collaboration is a force for good.
I hope this tutorial has helped you to take your first step becoming an open source contributor on GitHub. Check out our upcoming workshop for National Coding Week.
