GitHub for Mathematicians

A nice feature of collaborative authoring tools such as Google Docs and Overleaf is the ability for several collaborators to edit the same file synchronously, with a feature set similar to GitHub.dev.

Using the Extensions sidebar, search for and install Microsoft’s “Live Share” extension. Once installed, you will have a “Live Share” option in your bottom toolar. Clicking it will automatically copy a URL ending in https://.../join?[randomStringOfCharacters]. If you share this URL with a colleague (or colleagues) you trust, they will be able to collaboratively edit your repository’s text files with you via their web browser. When you commit your changes, they will be listed as co-authors of the commit.

A particular downside of Live Share (Section 5.1) is that it requires the repository owner to create the Codespace and provision the Live Share session. As a result, there’s no way for a collaborator to make a contribution via Live Share to a GitHub project without the active involvement of the repository owner.

To address this, one solution is for the repository owner to add other GitHub users as collaborators.

Collaborators are added by going to your repository’s Settings tab, using the Collaborators link in the sidebar. Each collaborator will need their own GitHub account, and must accept the invitation to collaborate before gaining access.

Once they have access, a collaborator can either use GitHub.dev (Note 2.4.2) or create their own Codespace (Definition 4.1.1).

Once a collaborator is working on a branch, they are free to edit as they wish, and can (and should) commit and push/sync with GitHub to persist their contributions to the team’s repository.

To facilitate communication among collaborators working on different branches, it’s good practice to open a draft pull request once a new branch is created.

With a draft pull request created, the contributor can continue to commit and push/sync to the branch until it is ready for review. The discussion features of GitHub can allow contributors to discuss the proposed changes, whether they are in draft or review-ready status.

Depending on the complexity or maturity of the project, you may wish to develop a review process with your collaborators, or simply use the PR workflow to clearly communicate when changes are being made to the main branch, and ensure no two collaborators make incompatible changes to the same branch. Whatever you choose, you’ll eventually want to incorporate these branched changes into your main branch.

As long as contributions are made using appropriate branches and pull requests, you will have minimal problems with conflicting changes made between different collaborators, with GitHub handling the merging process automatically, even if two collaborators edit the same file. (But not always, see Section 5.4.)

But a common error that I frequently make myself: what if you forget to create a branch with your work, and you acccidentally commit to main directly? The first safety rail I recommend is to set up a policy on your repository that will prevent this accidental commit to be pushed to GitHub.

Finally, there’s no button to push that will fix a commit made to the local copy of main accidentally, but there is a quick-enough fix nonetheless.

BRANCH=my-new-branch

git stash
git branch $BRANCH
git reset --hard origin/main
git checkout $BRANCH
git stash pop

One great thing about working with open source on GitHub is that not only can you collaborate with your trusted colleagues, but you can also work with collaborators who do not have write access to your repository.

Managing contributions from forked repositories is done using the same workflow as I recomend for collaborating with trusted colleagues that you’ve given write access to your repository (Section 5.2). The only difference is that an outside collaborator is creating branches and making commits on their forked copy of your project, not a branch of your original repository. But GitHub still gives essentially the same options for the outside collaborator to create a pull request to your project, without given them access to any data you aren’t already sharing with the public.

Those of us who work in open source typically love getting pull requests from random collaborators. For example, if you find a typo in this book, you can fxi it by creating a fork at https://github.com/StevenClontz/github-for-mathematicians/fork, editing the appropriate source/*.ptx file to fix the word, and open a pull request.

To come in a future revision of this handbook...