pcb-rnd knowledge pool
The common -rnd SVN commit log message format
commitmsg by Tibor 'Igor2' Palinkas on 2019-06-21 | Tags: howto, commit, log, format, syntax, message, svn, subversion |
Abstract: We use scripts for speeding up writing the changelog. The script uses svn commit log for input. Writing the changelog is still a lot of very boring manual work. To help that process and reduce the overhead, please stick to the commit message format specified in this document.
The most important parts to understand are:
- we want to process the commit log by software, so little details of the syntax do matter
- the changelog is read by the end user, so the commit messages need to focus on how your change is preceived by the end user
Commit message format
Whitespace matters. The fromat is case sensitive. All the punctures matter.
in BNF
<commit_msg> ::= "[" <topic> "] -" <action> ": " <text> <action> ::= "Add" | "Del" | "Fix" | "Change" | "Split" | "Move"
In plain text
[ topic ] - action : text
Example
[myplugin] -Fix: crash on missing background color in the header of the input file
Fields
topic
The project is informally split into topic groups for the changelog. These groups are often similar to the source tree layout, but not alwats. The purpose of this grouping is telling the reader, who is typically an end user with now knowledge of the source tree, about which conceptual part is affected by a change.
If you are unsure which group your change belongs to, do an svn log -v on the affected directiories and try to find a similar commit. Or ask the project leader.
action
Action tells the end user, from user pint of view, what to expect from the change. Typical values are:
- Add: new functionality added
- Del: existing functionality removed
- Fix: a bug in existing functionality fixed
- Split: split up functions, files, code, data, config, etc. into multiple smaller chunks - shall not affect how things work, should be invisible to the end user
- Move: move functions, files, code, data, config, etc. into a different location, without any other change - shall not affect how things work, should be invisible to the end user, unless it is about the location of installed files or affects content of installed human readable files (e.g. config files)
- Change: some details how an existing feature works changed, not because of any of the above reasons, but because we decided it should work differently for other reasons
text
A single line (do not use newlines, line wrap, etc.) of text that:
- very short summary of the change
- explaination on the reason of the change
Since svn diff shows what's changed, focus should be on the why not on the what . Please never include the name of the person who commited or the date when the commit took place and usually avoid including file names too: these are metadata automatically recorded by svn.
Always use a real subversion client. If you have to use some gateway and you are committing from some other version control system, make sure it does not append garbage, such as "signed off by:" lines.