Merge pull request #31 from dfe-analytical-services/add-commit-guidance

Add git commit message guidance

learning-development/git.qmd

@@ -96,32 +96,45 @@ However, you can still run the full suite of git commands by simply typing them
 ## Tips for using Git
 
 
+### Commits
 
-### Branches
+---
+
+The best advice is to just commit regularly, like you would if you were saving a word document.
+
+Each commit is a saved point in time that you can easily roll back to if needed. If you want to know more about how to do this, see the [reverting a commit](#reverting-a-commit) section below. 
 
 ---
 
-David Sands has produced a very helpful video on how to use branches in git, which also covers how to tackle merge conflicts if and when they arise:
+#### Commit messages
 
-<div align=center>
-<iframe width="640" height="360" src="https://web.microsoftstream.com/embed/video/6b56e063-294c-4103-b8b7-aacc4f1c9169?autoplay=false&amp;showinfo=true" allowfullscreen style="border:none;"></iframe>
-</div>
+---
 
-When you create a git project, it will automatically create a "main" (sometimes "master") branch for you. This is where code that has been QA'd and you are happy with should sit.
+The best advice for commit messages is to keep them clear, simple and brief. 
 
-- It is good practice to have at least one other branch, we tend to call it "development". This is the branch where you will be doing most of your work. To open a new branch, navigate to "branches" and click on the blue box highlighted below
+It is recommended to use the imperative tone e.g. `Add fix for joining pupil table` rather than `Added ...` or `Adding ...`. Other general recommendations include:
 
-![](../images/new_branch_git.png)
+- Keep it short (max 150 characters if possible) - committing regularly can help with this
+- Explain what the change is and why the change was needed. You generally don’t need to go into the detail of how the change was made as this should be visible from the code
+   - e.g., `Add x to prevent y` or `Add x so that y can z`
+- Don’t assume the reviewer understands what the original problem was
+   - would someone else looking at it, or even yourself in a week’s time know what the commit was doing?
+- Capitalise the first letter and don’t end with punctuation, it is unnecessary
 
-- Having two separate branches means that if anything goes wrong in the "development" branch, the "main" or "master" branch is still unaffected and runs without issue. This lets you test and QA the code more thoroughly before merging into your main branch.
+If you're struggling to know what to write, remember the reader (including future you) is unlikely to have much context when looking through the version log to find the right point in time, try considering the following:
 
-- When working on your project, make sure that you are in the right branch. You can check this by navigating to the "Git" tab in RStudio as demonstrated below.
+- Why have I made these changes?
+- What effect have my changes made?
+- Why was the change needed?
+- What are the changes in reference to?
 
-![](../images/select_branch.png)
+Never leave a commit message blank. The information you include could really pay off later when you need to remember what you worked on, or share it with other people.
+
+There are specific conventions outlined in [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/), that are worth familiarising yourself as you begin to use Git more. Following these conventions will help you write messages that are consistent with [over 100 million other Git users](https://github.blog/2023-01-25-100-million-developers-and-counting/) around the world.
 
 ---
 
-### Commits
+#### In RStudio
 
 ---
 
@@ -139,7 +152,29 @@ Once you are happy with changes and want them to be in the latest version of you
 
 ![](../images/pull_git.png)
 
-Committing regularly is strongly recommended as each commit is a saved point in time that you can easily roll back to if needed. If you want to know more about how to do this, see the [reverting a commit](#reverting-a-commit) section below. 
+---
+
+### Branches
+
+---
+
+David Sands has produced a very helpful video on how to use branches in git, which also covers how to tackle merge conflicts if and when they arise:
+
+<div align=center>
+<iframe width="640" height="360" src="https://web.microsoftstream.com/embed/video/6b56e063-294c-4103-b8b7-aacc4f1c9169?autoplay=false&amp;showinfo=true" allowfullscreen style="border:none;"></iframe>
+</div>
+
+When you create a git project, it will automatically create a "main" (sometimes "master") branch for you. This is where code that has been QA'd and you are happy with should sit.
+
+- It is good practice to have at least one other branch, we tend to call it "development". This is the branch where you will be doing most of your work. To open a new branch, navigate to "branches" and click on the blue box highlighted below
+
+![](../images/new_branch_git.png)
+
+- Having two separate branches means that if anything goes wrong in the "development" branch, the "main" or "master" branch is still unaffected and runs without issue. This lets you test and QA the code more thoroughly before merging into your main branch.
+
+- When working on your project, make sure that you are in the right branch. You can check this by navigating to the "Git" tab in RStudio as demonstrated below.
+
+![](../images/select_branch.png)
 
 ---