Updates after review

Author: aassuied-ps

site/posts/how-to-commit/index.qmd

@@ -1,6 +1,6 @@
 ---
 title: "How to write a good commit message"
-subtitle: "Keep easy trackchanges history for your project"
+subtitle: "Keep easy track changes history for your project"
 author: "alex"
 date: "2025-08-22"
 categories: [git, version-control, revision-history]
@@ -34,7 +34,7 @@ Despite the fact that making commit is mandatory when working on a Git repositor
 
 ### Keep clear history of changes
 
-Commonly, each program has a header that contains a *"Revision history"* part. Git commits can easily replace this part because it contains the main information of a classic revision history message (author, date and reason for change), associated to the full files comparisons, such as a before/after view.
+In traditional approaches, each program has a header that contains a *"Revision history"* part. Git commits can easily replace this part because it contains the main information of a classic revision history message (author, date and reason for change), associated to the full files comparisons, such as a before/after view.
 
 All the changes of a single commit are stored in the same place. It means if you work on a single task that request to modify several programs, you can summarize the changes within one message. You do not need to open each separated files one by one to look at what was done, when, and by who.
 
@@ -48,12 +48,6 @@ Even with several commits, you can have a clear view of all the changes when mer
 
 As Git is a version control software, and each commit is a snapshot done at a current state, it is easy to go back to a previous version of a branch using commit IDs.
 
-::: callout-caution
-#### Need feedbacks - hash
-
-I think talking about `git checkout` and `git reset` here is not useful. Maybe another blog post could be interesting. What do you think?
-:::
-
 ## When to commit?
 
 ### Commit one file at a time or several?
@@ -66,18 +60,18 @@ In the case of a debugging task over several files, one commit message per file
 
 When a change on a program affects the behavior of other programs that also needs to be updated, one commit for all the modifications can be done. Also when you decide to modify both a program and the associated documentation.
 
-::: callout-caution
-#### Need feedbacks.
-
-Need feedbacks.
-:::
-
 ## How to write a good commit message
 
 As a history tracking, a commit message should be concise and clearly explain **what** was done and **why**.
 
 It is important to have good commit messages because, as mentioned above, it can replace a classic track change history. The goal is to have messages that will help understanding the changes and will help during the quality control, review or audit steps.
 
+::: callout-tip
+#### Consolidate all commits of a branch
+
+Even with several commits, you can have a clear view of all the changes when merging to the source branch.
+:::
+
 ### Title
 
 The title should be very short (around 50 characters) and explain **what was done** on which file(s) (if relevant).
@@ -106,6 +100,12 @@ Using tags that to identify the location of changes can also be an option, such
 `TLF: create overview of AEs`
 :::
 
+::: callout-tip
+#### Keywords and source code management platforms
+
+So websites such as GitHub are able to recognize some keywords such as `closes` in the title, that will automatically perform an action on the issue or branch (for instance, `closes` will close the issue).
+:::
+
 ### Detail
 
 The detail explains **why** the commit needed to be done, the methodological or technical context, or any relevant information that needs to understand the commit.
@@ -114,6 +114,8 @@ It should contains, when relevant, the source (such as a new version of the stat
 
 It should be informative but also concise.
 
+Using source code management platforms (GitHub, GitLab, BitBucket, etc) allows a direct link to issues in the title or detail of a commit (for instance `Linked to #35`)
+
 Here is an example of a commit message including a title and the body (detail):
 
 ::: note
@@ -131,3 +133,32 @@ Here is an example of a commit message including a title and the body (detail):
 
 [conventionalcommits.org](https://www.conventionalcommits.org/en/v1.0.0/) gives tips and guidance for writing commit messages.
 :::
+
+::: callout-tip
+#### Using AI to improve commits
+Tools such as GitHub Copilot can help to write a good commit message by reviewing a branch and the updated done.
+:::
+
+## Examples of bad commit messages
+
+### Single keyword
+
+A message such as `fix` with no addition or detail is too vague. It is not possible to understand directly which file has been fixed and why.
+
+### Too wordy title
+
+The following title is way too long and difficult to read easily:
+
+`
+Update participant demographics summary dataset (ADSL) to include additional needed variables for geographical regions groups requested during the study team meeting on September 1st 2025 following the last version (1.2) of the SAP.
+`
+
+A better way would be to have a title like this one:
+
+`Add ADSL.REGION1(N)`
+
+And a detailed description such as this one:
+
+`Following study team meeting (01-SEP-2025).`
+
+`Done as per SAP (v1.2).`