To keep things simple, we follow the GitHub Flow in our development
process. In this workflow, the only hard rule that must always be
obeyed is that anything in the
main branch must be stable.
This means before you make any changes to the code (e.g. implement a new
feature, fix a bug, add a docstring/comment, etc.), create a new branch
main. Your branch name should be descriptive, so that others
can see what is being worked on (see Step 2,
below). Only after your code was tested, has no known bugs and works
stable, it can be merged back into the
The following demonstrates an example workflow that can be used as reference.
If you want to contribute to this project, you should first create your own copy of the project (a.k.a. fork). This step must be done only once (as long as you don’t delete your fork). If you already have your own fork of this project, go ahead to Step 1.
Go to the project repository on GitHub and press the Fork button in the top-right corner (note that you need a GitHub account for this). Afterwards, clone your forked repository to your local computer:
git clone https://github.com/<YOUR-USERNAME>/hpc_submit_scripts.git
You should configure a remote that points to the original (so-called upstream) repository:
cd hpc_submit_scripts/ git remote add upstream https://github.com/andthum/hpc_submit_scripts.git
In this way you can fetch the latest changes directly from the upstream repository (see Step 1).
Get the latest changes from the remote repository.
git fetch upstream git checkout main git merge upstream/main
As long as you have not commited anything to the
main branch of your
fork, Git will perform a so-called fast-forward merge (see the Git Book
chapter Basic Branching and Merging). If you want to keep your
main branch in sync with the upstream
main branch, you
should never commit anything directly to your fork’s
but only fetch and merge the upstream
main branch into your fork’s
Create a new topic branch (usually out of the
git checkout main git checkout -b topic/branch
Topic branch naming conventions:
Use short and descriptive, lowercase names.
Do not name your topic branch simply
maintenance, because these are (more or less) commonly used names for special branches or branch groups.
Use slashes to separate parts of your branch name. However, be aware of the following limitation: If a branch
spamexists, no branch named
spam/eggscan be created. Likewise, if a branch
spam/eggsexists, no branch named
spamcan be created (but
spam/spamis possible). The reason is that branches are implemented as paths. You cannot create a directory
spamif a file
spamalready exists and the other way round. This means, once you started branch naming without a sub-token, you cannot add a sub-token later. This is the reason why you should never name your branches simply
Use hyphens to separate words.
Use group tokens at the beginning of your branch names:
fix/<possible-sub-token>/<description>for bug fixes.
feat/<possible-sub-token>/<description>for new features.
dep/<possible-sub-token>/<description>for dependency updates.
docs/<possible-sub-token>/<description>for documentation updates.
chore/<possible-sub-token>/<description>for maintenance work.
Use sub-tokens where applicable and meaningful.
If you address a specific issue or feature request, reference this in your branch name, e.g.
Do not use bare numbers as one part of your branch name, e.g. do not name your branch
feat/issue/15. Otherwise, tab-expansion might get confused with SHA1 commit hashes.
Add your changes to the project.
Don’t forget to write tests for your code (see Writing Tests) ;-)
Check your code quality by using code formatters and linters (see the respective code guidelines for a list of which formatters and linters to use).
Many editors and integrated development environments (IDEs) offer to load the requested code formatters and linters as plugins. These plugins format and lint the code on the fly as you type or on each save. When using the corresponding plugins, you can skip this step.
If you have set up pre-commit, your code is automatically formatted and linted before every commit.
Run the test suites (see Running Tests).
If you did not touch the source code and did not write or change code examples in the documentation, you can skip this step. Also in other cases you might skip this step, because all tests suites are run automatically as part of our Continuous Integration (CI) workflow when pushing changes to the upstream repository. However, if the tests on GitHub fail, you might simply be asked to fix the failing tests before your code is reviewed.
git add path/to/changed/files git commit
Each commit should be a single logical change. Don’t make several logical changes in one commit. Go back to Step 3 as often as needed.
On the other hand, don’t split a single logical change into several commits.
Commit early and often. Small, self-contained commits are easier to understand and revert when something goes wrong.
Commits should be ordered logically. If commit X depends on changes done in commit Y, then commit Y should come before commit X.
Commit message conventions:
See Tim Pope’s note about Git commit messages.
The summary line (i.e. the first line of the message) should be descriptive yet succinct. It should be no longer than 50 characters. It should be capitalized and written in imperative present tense. It should not end with a period.
Start the summary line with “[Path]: Change”, e.g. “[lmod/palma/README.rst]: Fix Typo”. In this way other developers and maintainers immediately know which file has been changed. If you have a complex commit affecting several files, break it down into smaller commits (see above). If the path is too long to get the summary line within 50 characters, only name the file that has been changed or don’t name the file at all.
After that should come a blank line followed by a more thorough description. It should be wrapped to 72 characters and explain what changes were made and especially why they were made. Think about what you would need to know if you run across the commit in a year from now.
If a commit A depends on commit B, the dependency should be stated in the message of commit A. Use the SHA1 when referring to commits.
Similarly, if commit A solves a bug introduced by commit B, it should also be stated in the message of commit A.
While you were working on your topic branch, the upstream repository
might have changed. To avoid merge conflicts and to have an (almost)
linear history, pull the latest changes from the upstream repository and
rebase your topic branch onto the target branch (which is usually the
# Get latest changes git fetch upstream git checkout main git merge upstream/main # Rebase the topic branch onto the target branch git checkout topic/branch git rebase main
Immediately after rebasing, push your changes to your fork’s remote repository:
git push origin topic/branch
In order to get your changes merged in the upstream repository, you have to open a pull request from your fork.
Go to the repository of your fork on GitHub. GitHub should notice that you pushed a new topic branch and provide you with a button in the top-right corner to open a pull request to the upstream repository. Click that button and fill out the provided pull request template. Give the pull request a meaningful title and description that explains what changes you have done and why you have done them.
Either your pull request is merged directly into the upstream repository, your pull request is rejected or you are asked to make some changes. In the latter case, please go back to Step 3 and incorporate the requested changes.
Thank you very much for your contribution and taking all the long way down until here!