Contributing to the Documentation - a Tutorial

Let’s run through the steps needed for you to start contributing to the documentation. You should have read the overview, Contributing to the Documentation, first. To reiterate, We hold a repository (‘repo’ for short) of all the ReStructureed Text (RST) documents that comprise the Indicia documentation on the GitHub website. The administrator of the documentation website converts the RST into HTML for use on the public website.

Getting to Grips with Git

Let’s start by taking a look at Git. Git is a source control system used for organising and controlling files. It gives us a way of controlling and organising the documentation we are writing. For instance, we need to avoid people overwriting other contributors’ work by accident and it is also useful to track who has changed a particular document. In reality this is just a small selection of the kinds of control that need to be applied during the development of our documentation.

There’s really no way round the fact that to contribute to the Indicia documentation, you will need to get to grips with Git. You will need to work with GitHub and a Git client on your computer. These are two different but related things as you will see.

A good explanation of the general workflow we are recommedning is given in this blog: The beginner’s guide to contributing to a GitHub project.

Get a GitHub account and fork Indica-docs

The GitHub website implements Git version control and acts as a cloud-hosted hub where open source projects can hold their source code. Your first task to is to register and get an account for that website. This is very straightforward and, needless to say, free!

https://github.com/

Members of the Indicia project team can work directly with the indicia-docs GitHub repo, but you don’t have to be a member of the project team to contribute to the documentation. Instead you can use the Fork button (top-right on the indicia-docs GitHub rep page) to copy the entire repo to your own account. The workflow is that you will modify this fork and then make a pull request to have your changes merged into the original repo. So if you haven’t yet forked the repo to your own GitHub account, do that now.

Although you can edit files directly on your fork on the GitHub website, it is much more convenient to make a copy on your local computer, work there and then update your fork before requesting that your updates be merged into the main repo.

This is where you need a Git client of some sort on your computer.

Set up your Git client

There are many Git clients out there, but we recommend that you install Visual Studio Code (VS Code). Not only is it a fully featured code editor that you can use to edit your Indicia RST files, but it is also a Git client.

If you use VS Code you can choose whether to use its GUI to interact with Git or to use Git from the command line (which you can do through the Terminal window from within VS Code if you like). Or you can used a mixture of the two. Sometimes using the Git command line interface is unavoidable, so for the sake of simplicity this tutorial sticks with the Git command line interface.

Clone your fork to your local computer

Once you have installed VS Code on your computer, you will also have installed Git. So now we can take a local copy of our fork of the Indicia documentation.

Find a folder on your computer where you want to copy the indicia-docs folder from your fork and open VS Code there. In VS code, open a Terminal window. If the working directory of your terminal window is not the folder where you want to create the indicia-docs folder, first change into that folder.

Now type the following command in the terminal:

git clone path_to_your_fork

To get the value for ‘path_to_your_fork’ go to your GitHub repo (your forked repo) and click on the green ‘Clone or download’ button. You sill see the URL of your repo which you can copy and paste into the terminal window. So your actual command will look something like this:

git clone https://github.com/burkmarr/indicia-docs.git

(But it will reference your own fork.)

Running this command will result in a folder called ‘indicia-docs’ on your computer which is ‘tracked’ by Git.

Bringing your remote and local repos into line

To keep your local repo and your remote forked repo up to date with work done by other people, you will periodically need to pull down changes made by others from the main repo into your local repo and push these to your forked repo. To update your local repo and your fork with the latest changes from the main repo, you perform these git commands:

git pull upstream master
git push origin master

This is normally something you’d do before undertaking a piece of work of your own.

Note that if you have carried out work on files which have not yet been incorporated into the main repo, you might at this point get ‘merge conflicts’ (pulling actually carries out a Git merge). It is beyond the scope of this tutorial to cover dealing with merge conflicts, but there are plenty of Git resources on the web to help with that. In any case, if you undertake the pull and push before you start work, you may never need to deal with a merge conflict - instead the administrator of the documentation will sort out any conflicts when processing your pull request (covered later).

Create a branch to work in and do some work!

Branching is a fundamental part of the Git workflow. It helps us isolate changes we make from the main source until we (or the project administrator) chooses to merge them in.

Create and checkout a branch like so:

git checkout -b your_branch_name

Keep branch names short and descriptive. Because you where already in indicia-docs ‘master’ branch, you have just created a complete copy of the master branch and checked it out - which means that any changes you make to files now will occur in that branch.

Now you can use VS Code to edit and save files etc. You can use and extension like ‘reStructuredText’ to preview changes you make to files.

When you have completed the work you wanted to do in that branch you can commit the changes you made. Note that this only updates your new branch - it doesn’t change the master branch. To commit all the changes you made, type:

git commit -a

An editor will appear in VS Code with text that summarises the changes you have made. You must now edit the first line of this to create a git commit message. Keep this short - no more than 50 characters. Underneath this, you can insert lines to give a more detailed explanation of your changes. Each of these lines should be no more than 72 characters. (These line length limits enable Git to format commit messages nicely. Longer line lengths look bad.)

When you are happy with your commit message, save the file and close the edit window. You will now see the commit complete in the terminal window.

Note that you can actually make as many commits as you like as your work progresses - there’s no need to wait and do one big commit at the end. The more you use Git and understand its features, e.g. for rolling back changes, the more likely you will want to commit smaller chunks of work. Note that we have also glossed over a step called adding or staging changes which you can do before committing (the ‘commit -a’ command stages and commits in one fell swoop). Again the more you use Git, the more likely you are to want to learn about the subtleties of separate staging and committing.

Push your new branch to your forked repo

Now that you have committed your changes in your local work branch, you can push these to your forked repo like this:

git push -u origin your_branch_name

This will create a new branch on your GitHub forked repo with the same name as your local branch and include all the changes you committed.

Open a pull request on the main repo

From your GitHub account, go to you forked repo and click the on the ‘branches’ link. You should see a list of branches that includes the default ‘master’ branch and the branch you just created (which will be listed twice - once under ‘your branches’ and once under ‘active branches’). Click on the new pull request button next to your branch (it doesn’t matter which one of the two).

That will take you to a GitHub window like the one shown below.

Making a GitHub pull request.

Look at this part in particular:

GitHub pull request detail.

GitHub has taken us to the pages of the original repo from which you forked. A pull request has been created against this original repository from the branch you created in your fork.

Edit the title of the pull request and, where it says ‘write’, explain the changes you have made. Don’t skimp on this - you want your changes to be accepted so give the administrator - the person that will process the pull request - as much information as they need to help them decide whether or not to accept it.

Of course they can review the detail of the changes you have actually made, but your description will help put that detail in context.

Note that the green ‘Able to merge’ text tells the project administrator that none of the changes in this pull request conflict with other changes already committed to the project which means that it can be easily merged if they decide to accept it. If there are merge conflicts, the administrator will decide how to deal with those if the pull request is accepted.