# 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.