By Lieke de Boer and Mateusz Kuzak
A step-by-step guide to one way (of many possible ways) of handling a contribution to lesson material hosted in a GitHub repository. To jump directly to the step-by-step guide, scroll down to “Step-by-step guide: how does it work?”.
This blog post was written to accompany a session on collaborative lesson development at the Open Science Festival on 31 August, 2023 in Rotterdam, the Netherlands. However, this guide stands alone and can be used as a refresher for those looking to make contributions, or help in the approval process of others contributions to collaborative projects on GitHub. It assumes no knowledge of programming, git or version control and exclusively relies on the online GitHub graphical user interface. The dummy repository that was used in the session during the Open Science Festival can be found here. Screenshots were taking in this repository.
GitHub does not rely on you and your collaborators to work with the same combination of online file sharing system, email server and task manager, for example. All elements of project management can be handled within GitHub itself, which you access in the browser. GitHub provides an infrastructure that can be like like Google Docs, Trello, Email and ToDo at once.
On top of that, GitHub has some extra functionality that sets it apart from the tools mentioned above and fit in well with Open Science practices. Some examples of these are:
Different repositories can have different rules about how to contribute to a repository. It is always a good idea to first check the contributing guidelines and try to stick to them as much as possible. Contributing guidelines are usually found in the root repository folder:
As an outside contributor, the first thing you may do when you find an existing lesson repository on GitHub is to browse the list of issues. Issues are the perceived omissions or problems, wishes, or any other desired changes or additions listed by the lesson maintainers and anyone interested in improving the lesson. Each issue is usually a single problem with one part of the material. You could think of the issues as a shared to-do or wishlist of those who develop and use the repository’s lesson material.
You may have your own issue to add, or you could browse through the list of issues to see if there is something you can fix in the list.
For the purpose of this guide, we are going to assume that a lesson contributor (with GitHub name @liekelotte) has realised that there is no citation file present in the lesson repository. This means others interested in the lesson do not know how to cite this lesson material, if needed.
If you would like to see something improved about the material, but there is no issue for it, you should make your own issue. This can be done by pressing New issue at the top right of the issue list. A dialogue window will open where you can describe in short (title bar) and longer (in “write”) what issue you would like to see solved:
If you already know who will be able to solve the issue for you, you can assign a GitHub user in the “Assignees” panel on the right. You can also assign issues to yourself, to show others that you will work on it. In this case, @liekelotte thinks that @PabRod should be able to do this.
You can also add labels to the issue, to help other contributors and maintainers filter through the issues more easily. GitHub repositories come with standard labels, but these are editable:
The person assigned to the issue will likely make the desired changes in the repository (but being assigned is not a requirement for working on the issue – it just allows all contributors to the repository to maintain an overview). The assigned collaborator may need some more information. Luckily, there is space in the issue to have a discussion:
(In this citation file example, they can be helped with the link to cffinit, a tool that lets them easily create a citation file. You can see the closed issue here for the full conversation – but its content is not relevant to the methods described here.)
When the problem is clear, the person assigned to the issue can make the changes. For that, it is important they make a note of the issue number. This is issue #111.
Now the changes can be made. In general, we have two main options when making a change to a repository: creating a new file, or editing an existing file.
In this particular case (Issue #111), the issue was centered around a missing file. Because we are only using the online GitHub interface, this means that @PabRod will create a citation file and upload it to the repository. It is common practice to save citation files to the root directory of a repository. In GitHub, this is the directory you are in when you press the Code tab in the repository. A new file can be added by pressing “Add file”. In this case, we will then choose “Upload files”
The resulting dialogue window will allow us to upload files to the repository.
Let’s say the citation file already exists, but a change has to be made to it. In this case, we navigate to the file in the repository, and edit the file.
Making a commit in GitHub is similar to pressing “Save” in a text editor. However, whenever you make a commit in GitHub, you should write a commit message that describes your change. There are many conventions on what this commit message should entail, which you can read more about here.
For now, we will simply describe what we did. There are a few important things to note here:
When @PabRod now opens the Code tab, he can click “Compare & Pull Request”. A Pull Request can be in two modes: Ready, or Draft mode. When you are working on an issue that takes multiple changes in multiple files, it is best to keep working in Draft mode for a while. When the pull request is ready to be reviewed, assign the review to the person who opened the issue, or someone else who may be able to review the changes for you.
In this case, @liekelotte created the issue. It makes sense that @PabRod requested their review.
In @liekelotte’s view, we see a notification:
@liekelotte’s review was requested on @PabRod’s pull request. Great! Let’s have a look by pressing “Add your review”.
By clicking on “Files changed”, the reviewer can see what has changed, compared to the main branch, on the Pull Request that was submitted. Anything that is added compared to the main branch shows up in green highlighting. Everything that is removed shows up in red highlighting.
In this case, we see only green highlighting, since a whole new file was added.
At first glance, everything looks good, but @liekelotte spotted a typo in her own name: This should be Lieke, not Like.
Luckily, it’s easy to make comments or suggestions on specific lines of the changed files. Do this by pressing the small +
sign next to the line where you have a comment or suggestion.
If you have a quick and easy suggestion you’d like to propose to your contributor, you can do this by pressing +/-
sign (“Add a suggestion”).
Clicking that button adds a copy of the line you can suggest changes in between three inverted ticks. When the reviewer changes something between these ticks, it will show up as a suggested change to the pull request. The contributor (@PabRod) can decide to simply commit the suggestion in the next iteration.
Pressing “start a review” shows the suggested change to this line as follows:
@liekelotte may have additional comments, which can be written in specific lines, or as a general comment in the review. When as a reviewer you think you cannot merge the PR before the changes are addressed, you can choose the option “Request changes” when you submit your review. Make sure you always thank contributors for their contributions, and be polite about the changes you believe should still be made:
We click “Submit review”, and the ball is in @PabRod’s court again.
@PabRod will receive a notification that @liekelotte requested changes. He can inspect these changes.
When a reviewer has made a suggestion, it’s easy to commit the suggestion by pressing the “commit suggestion” button, and writing a commit message (in this case “Update CITATION.cff”) – @PabRod writes an apology for his mistake in the longer field:
That’s one change addressed! But another change was requested. @PabRod can address this change by navigating to the branch this new file is in. After all, the Pull Request hasn’t been merged into the main
branch yet, so the file will not be visible there! Below, you can see how to navigate to other branches from the main branch, when you’re at the “home” page of the repository.
@PabRod will select the branch citation-file
, which he created in step 4, from the drop-down menu.
When in this branch, on the left, you can select the file you want to amend. On the right, you can click “edit” to edit the file. Now he adds a few keywords:
When committing these changes, GitHub will automatically offer to add the commit to the current branch. In this situation, no new branch needs to be created, since this is a branch that suggests a new feature already:
Now, @PabRod can re-request review from @liekelotte:
In the same way as before, @liekelotte will look at the Files Changed tab for the Pull Request her review was requested on. She can see the changes: her name is now spelled correctly, and keywords have been added:
This is what she wanted! She’s grateful. She adds her review (‘Review changes’), and approves the PR:
Then, she merges the pull request:
The branch citation-file
can safely be deleted, since we do not need that copy of the repository anymore:
Remember how @PabRod wrote “Closes #111” in his commit? When a PR with a message like this in one of the commits, or in the PR text gets merged, the issue with the number after “Closes” or “Solves”, automatically gets closed in the repository. We can inspect this really happened in the list of closed issues by navigating to issues and clicking “Closed”:
You did it!
This may seem like a long and complicated process for such a small change, but it is very useful in the context of changing lesson material, which can have a lot of different chapters, elements, and point of improvement. GitHub is a great way of keeping track of all of them, while having a clear view of who is assigned to what issue. This makes working asycnhronously convenient!
We hope this guide was useful for you! If you have any feedback, additions or questions, please email rstnl@esciencecenter.nl. We’d love to hear from you!
This blog post was partially inspired by lesson material on lesson development by the Carpentries. You can read about more working with GitHub features for lesson development in their material on collaborative lesson development and working with newcomers.