---
# System prepended metadata

title: git guidelines

---

# git guidelines

This is just a draft and is open up for discussion. I have seen a lot of these practices applied in other
projects and can appreciate the result. 

## git commits

Good git commit messages can help other developers (or your self) in the future better understand
why certain changes were made.

Good practices:

- Keep the message short and concise, 72 chars is usually the guideline.
- Try and write a commit message that completes the following sentence: "This commit will ..."
- Adding Jira issue id's to commits makes it very easy to track back changes to a specific issue.
- Group changes in relevant commits. Separate refactoring from actual changes for example.
- If you can't summarize your changes in a short message than maybe the commit could have been split up more.

Bad commits:
```
ce72c94 - update gitlab-ci
d47rc81 - update
d47rc81 - fix 
25bb597 - plsup-1234
```

Good commits:
```
ce72c94 - PLDEV-1337 Update gitlab-ci base image to latest version
25bb597 - PLSUP-1234 Fix loadbalancer health check
```

There is always the git commit message body to add even more context

## merge requests

- Use the Jira issue id in the title. With the GitLab-Jira integration it's usually clickable and takes
  you straight to the relevant issue, it also makes it easier to find merge requests for an issue.
- Add a title and description to give the reviewer some context. 
- If needed use the descriptino to explain why certain choices were made, if the commit messages don't already cover this. 

Good: 
`PLDEV-1234 Update helm chart to use persistent volume`

Bad:
`feature/PLDEV-1234`
`Update chart`


## clean git history

A lot of things we work on require a bit of trial and error and often its easier to do so by committing and letting the pipeline run.

This might result in git history like:

```
478d285 - Update config.yaml
c93c7ab - Update config.yaml
9ced969 - Update config.yaml
505ab93 - Update config.yaml
e81b9ea - Update config.yaml
ce72c94 - Update config.yaml
0027210 - Update config.yaml
2cf07fa - Update config.yaml
```

Why care?
- The additional commits clutter the git history, drowning out more useful info.
- It's much easier to resolve merge conflicts with 1 commit than with 20

This can easily be prevented by cleaning the branch up with interactive rebase.
To edit the last 8 commits you can use: `git rebase -i HEAD~8`

Use `fixup` to merge the changes up (the latest commits are at the bottom):
```
pick 478d285 - Update config.yaml
fixup c93c7ab - Update config.yaml
fixup 9ced969 - Update config.yaml
fixup 505ab93 - Update config.yaml
fixup e81b9ea - Update config.yaml
fixup ce72c94 - Update config.yaml
fixup 0027210 - Update config.yaml
fixup 2cf07fa - Update config.yaml
```

You can also remove (or comment out) a line to remove the commit all together.
Other useful options: edit to dive back in to a specific commit and reword to change a commit message.

If you know you are making additional commits that you want to merge in to the previous one you can have your commit start with `fixup!` if this is our git history:
```
pick 478d285 - Update config.yaml
pick 8c5c7f1 - Some unrelated change
fixup c93c7ab - fixup! Update config.yaml
fixup 9ced969 - fixup! Update config.yaml
```

We can run interactive rebase with autosquash: `git rebase -i --autosquash HEAD~4`
It will automatically mark the commits with `fixup` and put them in the right order:

```
pick 478d285 - Update config.yaml
fixup c93c7ab - fixup! Update config.yaml
fixup 9ced969 - fixup! Update config.yaml
pick 8c5c7f1 - Some unrelated change
```

Note: Rebasing changes requires force pushing them. Only do this in your own branch, never
in shared branches.