Blog

Collaborative lesson development with GitHub

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.

Why would I want to use GitHub to collaboratively develop lessons?

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:

Issue Tracking: You can use GitHub’s “issue” tracking system to create tasks, report problems, or suggest enhancements to the lesson material in a repository. This provides a structured way to manage the lesson development process and prioritize work.
Attractive Web Pages with Template Repositories: GitHub provides the functionality of template repositories, which can be used to create visually appealing and user-friendly web pages for educational materials. Tools like GitHub Pages and static site generators can turn a repository into a well-structured website that showcases lessons in an organized and accessible way. The Carpentries has a template that we use for our lessons at the eScience Center (example of a lesson), which you can freely use as well!
Collaborative Editing: GitHub allows multiple users to contribute simultaneously through pull requests and issues. The review process is structured and comprehensive.
Transparency and Openness: GitHub encourages transparency and open collaboration. Anyone can see the progress, discussions, and contributions, which can foster a sense of community and attract potential contributors.
Forking and Contributions: Others can make a “fork”, essentially a copy of your repository to create their own version, or they can contribute improvements to your content. This can lead to a wider distribution and potential for improvement of your lesson materials.
Branching and Merging: GitHub allows you to create branches for different features or changes. Collaborators can work on their own branches and merge them back into the main content when ready. This prevents conflicts and ensures a smoother collaborative process.
Repository structure: GitHub’s repository structure encourages separation of concerns. You can organize different components, topics, or lessons within separate folders or directories. This makes it easy to manage larger projects like developing large courses.
Code Reusability: If your educational materials involve code samples or scripts, GitHub makes it easy to share, reuse, and update code snippets across different lessons.
Long-Term Availability: GitHub is a well-established platform. This ensures that your educational materials will likely be accessible and editable for years to come.
Customization and Automation: GitHub provides features that allow you to automate various processes. For instance, you can automatically build a webpage and publish lesson materials when changes are integrated.
Version Control: GitHub provides robust version control, allowing you to track changes, revert to previous versions, and see who made what changes. This is crucial when collaborating on educational materials, as it helps maintain a clear history of edits and updates.

Step-by-step guide: how does it work?

0. Check out the contributing guidelines

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:

1. Browse through the issues (anyone)

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.

2. Create or assign an issue (collaborator or reviewer)

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.)

3. Make changes in the repository (collaborator)

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.

Option 1: creating a new 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.

Option 2: editing an existing file

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.

4. Commit the change you have made (collaborator)

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:

@PabRod describes in the short text bar what he has done for this commit only.
Below the short text file, there is space for more elaboration. This is where the issue number comes in handy. If you make a commit that you think completely solves an issue, you can use this space to write “Closes #[issue number]” or “Solves #[issue number]”. When the changes are accepted by those who review the changes, that issue will automatically be closed. Note that an issue may take several commits to close a single issue, because multiple files have to be changed. In such cases, do not write #“Closes #[issue number]” or “Solves #[issue number]” in this field. We will discuss in the next steps how to handle those cases.
As an outside contributor to the repository, you always have to create a new branch when you make a contribution. You should give this branch a sensible name, so that you can find it later. In this case, @PabRod called it “citation-file”.

There is an exception to this: In some cases, you may fork (or copy) the repository and make the changes in your own fork. You can then open a pull request to suggest those changes to be integrated in the original repository. In that case, you do not have to create a new branch. Forking happens when contributors do not have writing permissions on the repository they want to contribute to. Anyone can usually fork a repository, whereas you need to be a part of an organisation to create a branch on a repository.
We can see that @PabRod is starting a Pull Request (often called a PR) by creating a branch. A pull request is a proposal to whoever owns the repository, to integrate the proposed changes into the default branch of the repository. This branch is called the “main” branch, and is the current working version of the respository.

5. Create a Pull Request and request a review (collaborator)

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.

6. Review the Pull Request (reviewer)

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.

7. Inspect the comments and proposed changes (if applicable, collaborator)

@PabRod will receive a notification that @liekelotte requested changes. He can inspect these changes.

8. Address the reviewer’s comments (if applicable, collaborator)

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:

9. Inspect the updated Pull Request and merge when ready (reviewer)

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:

10. Delete the branch (reviewer):

The branch citation-file can safely be deleted, since we do not need that copy of the repository anymore:

11. Check that the issue is closed (all):

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”:

12. Celebrate!

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.