Skip to content

Commit Message Format

Jump to bottom
John Haddon edited this page May 20, 2021 · 4 revisions

The Gaffer project has dragged on for some time, but has not yet descended into chaos. This page documents our standards for commit messages.

Subject line

  • Start with a one-line subject, no longer than 70 characters. This fits inside GitHub's commit view without being truncated.
  • Start the subject with the name of the class or module being edited, followed by a colon. For example, "ImageTransform :" for edits to the ImageTransform node or "GafferScene :" for broad changes to the scene module.
  • Use the imperative mood rather than the past tense. For example "Fix bug..." not "Fixed bug...". This may feel awkward at first, but matches standard Git practice and anecdotally makes it easier to compose meaningful messages inside the 70 character limit.

Body

  • Leave an empty line between the subject and the body.
  • Explain what is being changed and why, so that a fellow developer has enough information to evaluate the change.
  • Use Markdown formatting to improve clarity where relevant.
  • Include Fixes #100 to automatically close any issues fixed by the commit.

Example

GraphComponent : Add `reorderChildren()` and `childrenReorderedSignal()`
    
Rationale for passing a new vector of children to `reorderChildren()` :
    
 - We want to support completely arbitrary reorderings. This rules out more limited function signatures such as the `oldIndex, count, newIndex` discussed in #3922.
 - It is easier for client code to reorder a container of children directly than it is to work indirectly via indices as with the `sparseOldIndices, sparseNewIndices` signature discussed in #3922.
 - We want any reordering to be achievable in a single function call, yielding better performance.
    
Rationale for passing a list of source indices to `childrenReordered()` and `childrenReorderedSignal()` :
    
 - Client code may want to reflect the change of order in a parallel data structure, such as the widgets in a UI.
    
Fixes #3922.
Clone this wiki locally