[Readme] How to contribute code
The aim is to always maintain a working master
branch. "Working" means that all tests in the continuous integration (CI) pass.
The tests do not guarantee a bug-free state, but everything that is tested works.
The main reasons to maintain this state on master
are:
- "Release quick and often", i.e. whenever required, and without spending weeks of debugging to get the tests running again.
- Isolate bugs faster, which means reduced debug time. When the
master
passes all tests and your new feature does not, you only have to look for the code changes of your new feature, which is a pretty good starting point for debugging.
Ways to contribute code are:
Optimally, there is already an existing issue that you want to solve. If there is, link the issue in your commit messages (i.e. #[ISSUE_ID]
) or your merge request description. Gitlab automatically links all commits/merge requests with this issue and it is easier to find issue related code.
Standard work-flow
- branch from
master
(or any other branch if applicable) - Make this branch a merge request in gitlab https://gitlab.lrz.de/vadere/vadere/merge_requests .
- When you push to a new branch, gitlab immediately suggests to you to make this branch you pushed at to create a merge request.
- You can create a branch and merge request with one click from an existing issues directly with "Create merge request".
- For an example, there is a merge request attached at the bottom of this issue.
- Optionally, if you intend to work for longer, mark the branch name with "WIP:" (Work in progress), so everyone is aware to not merge until the WIP status is resolved. Gitlab offers a button to add/remove this status.
- Push all new code (refactoring, bugfix or new feature) to this branch.
- After your implementation is complete, wait until the continuous integration passes. You get usually an email if it does not.
- Solve all merge conflicts in your branch/merge request (and not on
master
). Gitlab checks for you if there are conflicts in the merge request. - After your work is done, all potential merge conflicts are resolved and your merge request passes the CI, then you can merge to
master
. Click the option "remove branch", which removes the underlying branch you pushed your code to after successful merge. For a new code contribution you can create a new branch. Note: you may also want to remove the branch locally.- You can also use the option "Merge when pipeline passes" in your merge request. Then you do not have to wait for the CI.
- Optionally: If there are a lot of commits that were just work in progress for a single issue, you may choose to squash the commits when merging, i.e. all commits are grouped into one on
master
which keeps the history clean.
"Small commits"
If you just commit something you are very sure it doesn't break anything, go ahead and push directly on master
.
master
I wrote a new test that would fail on The master
is not bug-free then. But we still need it to pass all tests. There may be other merge requests relying on a working master
. Therefore, proceed with the standard way: Create a merge request and first fix the bug, then add the test (both in a merge request). The concept is that the master
always fulfils the current set of tests.
master
fails?
What to do when the If the CI happens to fail on master
after you committed/merged new code and it is certain that this the cause, then undo your commit on master and proceed the standard way (i.e. create merge request with your commits). Compare your code to the (now running again) master, and look out on what is causing troubles.