SPM Development with Git and GitHub¶
We use the Git version control system for the development of SPM. GitHub is used as the collaborative code hosting platform (with a local mirror using Gitea): the authoritative copy of the SPM repository is available at spm/spm.
We provide here instructions to interact with the SPM repository using the GitHub Desktop. This mainly concerns Windows developers – we also mention the command line equivalents when relevant. For Linux users, additional steps are required to enable SSH authentication.
Git Installation¶
First, please install the GitHub Desktop:
Once installed, you need to authenticate with your GitHub account. To do so, follow the online instructions:
Two-factor authentication (2FA)
Two-factor authentication (2FA) is not required yet but might be by the end of 2023. See here for instructions on how to configure 2FA on your account.
You also need to install a Git command line tool. On Windows, we recommend:
During installation, you can accept most defaults. There are three options to be careful about (“PATH environment”, “line ending conversions” and “default behavior of git pull”), and you should select the choices as below:
If you do not have the administrative permissions to install Git as described above, try and install 64-bit Git for Windows Portable to C:\wtcnapps\ and add the directory containing git.exe to the Path environment variable for your account.
Git Configuration¶
Username and commit email address¶
Git commits are associated with a name and email address. GitHub then uses the email address to associate commits with your account on GitHub.com. It is therefore essential to set these before making any commit (and to set them again on all computers).
The instructions to set your commit name and email address in GitHub Desktop are available here:
The command line equivalent is:
If you use another personal email for most of your repositories, make sure to set the SPM repository to specifically use your institutional email address:
This can also be done with GitHub Desktop by following these instructions.
Note
Note that you can associate multiple email addresses with a single GitHub account.
Merge Strategy¶
The default of git pull to reconcile divergent branches is to call git merge. Here this default is changed to call git rebase instead. This has the advantage of creating a linear history, like in a traditional SVN workflow.
This is equivalent to using git pull --rebase.
To apply this setting from GitHub Desktop, you need to open the command prompt by selecting Repository then Open in Command Prompt from the top menu and enter the above command line.
Enforcing a linear commit history
Note that the option to require a linear history has been enabled on the SPM repository. This prevents from pushing merge commits to the main branch.
Git autostash¶
Pull with rebase will fail if you have unstaged changes. One way around this if you’re not ready to commit your changes is to stash the changed before doing a pull (git stash) and then restore then (git stash pop) afterwards. This can be automated by using the autostash option of git rebase.
This is equivalent to using git fetch followed by git rebase --autostash (or git stash, git pull, git stash pop).
As before, to apply this setting from GitHub Desktop, you need to open the command prompt by selecting Repository then Open in Command Prompt from the top menu and enter the above command line.
Clone the SPM repository¶
Follow these instructions with the SPM repository: https://github/spm/spm
From the command line, the equivalent is:
For Linux users, authentication will require SSH key generation.
Git Commits¶
After editing some files in the main branch, select the changes to include in a commit, write a commit message and push the changes to origin:
From the command line, this is obtained with:
Ideally, “each commit should be a perfect, atomic unit of change”. Do commit related changes, commit often but don’t commit half-done work (use branch or stash instead).
Commit Messages¶
Use the imperative and prefix the commit message with one of:
- New feature
- Enhancement
- Bug fix
- Documentation
- Refactoring
- Maintenance
- Test
You should be able to suffix a commit message to the phrase “If applied, this code will …”.
Commit messages should begin with a short summary of the changes (up to 70 characters) followed by a blank line and the body text, i.e.:
Enhancement: replace this with that in such and such
Longer description that might contain bullet points:
* item 1
* item 2
Git Workflow¶
We are using a Centralised Workflow. This is also called Trunk Based Development (see this article for a discussion). Popular other workflows include GitHub Flow and Gitflow.
git pull is used to incorporate upstream changes into the repository. The --rebase option tells Git to move all of the local commits to the tip of the main branch after synchronising it with the changes from the central repository. Extracted from the Atlassian documentation.Pull Requests¶
Recommendation for pull request reviewers: When merging, we generally like squash+merge. Unless it is the rare case of a PR with carefully staged individual commits that you want in the history separately, in which case merge is acceptable, but usually prefer squash+merge.