How to write a good commit message

[aassuied-ps]

There are some sites that already give good practices. But I think we could have our own blog page, with standard recommendations and perhaps some of our own advices.

Maybe this issue is overlapping with #35 .

[RitaPecuch]

I agree that this is a good topic, as one of the biggest issues I see at my company is commit messages that are extremely vague. As a general rule, I find that one sentence is sufficient to describe changes that have been made, and short enough that it is not too much extra work to commit changes. A few points that have been effective for us:

• Focus each commit on a single purpose:
  • Commit after writing a new function/module/other functional block of code (commit message describes basic purpose of the code block)
  • Commit when modifying an error (commit message describing the error that was fixed)
• Some prefer to reference Jira tasks or some other type of reference IDs for code criteria to avoid having to summarize information that is already documented elsewhere.

I have also noticed that if using GitHub Desktop, which has pre-written default commit messages, it is more common to see vague common messages (i.e. "modified server.R") because some of our developers do not change them. I am not sure if anyone knows if there is a way to disable this setting to force commit messages to be written out?

[PallabiniDash]

In clinical programming, a good commit message should clearly explain what you changed and why.
Start with a short summary like: ADaM: Derive TRTSDT and TRTEDT in ADSL.
Be specific, mention if you added a new variable, fixed a derivation, or updated a TLF output.
Use helpful tags like SDTM:, ADaM:, or TLF: so others know what the change relates to.
Try to avoid vague messages like “updated program” they don’t help during QC/ Review or audits.
Writing clear commit messages saves time later and helps with traceability.