Automating CHANGELOGs via enforced commit message conventions
Maintaining CHANGELOGs for engineering documentation is a challenge. Ensuring a clear commit message convention reduces complexity and improves functionality.
Whenever updating documentation, ensure clear and scoped commit messages. For example:
"docs: updated power values to ensure specification compliance !123 RM456"
This tells us the scope of what users updated in our document (docs), as well as a reference to our GitLab as well as our engineering change management platform (RM456). We can enforce this via GitLab Push Rules.
We can then use Git commands to generate our CHANGELOG automatically or as needed.
If needed, we can produce patch diffs from the relevant Git commits and output them to HTML. This will show updates between releases without including irrelevant changes.
It s the job of the Technical Writer to then ensure clear commit messages for a given Merge Request and include the correct references.
Regex enforced commit messages via Push Rules:
\((RTL|TB|SCRIPT|DOC|SVA|FPGA|CONFIG)(-refs #(\d+|None))?\): .*|(Merge branch.*)
Git log command to show the CHANGELOG between the last release and the latest:
git log --format='%h %s' 62003a7c..HEAD
Git show command to display document text changes
git show -p --ignore-space-change --format=%b 62003a7c