Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-1182

Adopt guidelines on contents and format of git commit messages

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: SAT
    • Labels:
      None
    • Team:
      Architecture

      Description

      The question of what makes a "good commit message" occasionally comes up. I feel that this document:

      http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

      presents a reasonable set of guidelines and I propose the SAT adopts it as a part of our software development standards.

        Attachments

          Issue Links

            Activity

            Hide
            frossie Frossie Economou added a comment -

            FYI, here are the Perl core commit message guidelines, which I quite like (they are consistent with the above, but a bit more general)

            Commit message

            As you craft each patch you intend to submit to the Perl core, it's important to write a good commit message. This is especially important if your submission will consist of a series of commits.

            The first line of the commit message should be a short description without a period. It should be no longer than the subject line of an email, 50 characters being a good rule of thumb.

            A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will only display the first line (cut off at 50 characters) when presenting commit summaries.

            The commit message should include a description of the problem that the patch corrects or new functionality that the patch adds.

            As a general rule of thumb, your commit message should help a programmer who knows the Perl core quickly understand what you were trying to do, how you were trying to do it, and why the change matters to Perl.

            Why

            Your commit message should describe why the change you are making is important. When someone looks at your change in six months or six years, your intent should be clear.

            If you're deprecating a feature with the intent of later simplifying another bit of code, say so. If you're fixing a performance problem or adding a new feature to support some other bit of the core, mention that.

            What

            Your commit message should describe what part of the Perl core you're changing and what you expect your patch to do.

            How

            While it's not necessary for documentation changes, new tests or trivial patches, it's often worth explaining how your change works. Even if it's clear to you today, it may not be clear to a porter next month or next year.

            A commit message isn't intended to take the place of comments in your code. Commit messages should describe the change you made, while code comments should describe the current state of the code.

            If you've just implemented a new feature, complete with doc, tests and well-commented code, a brief commit message will often suffice. If, however, you've just changed a single character deep in the parser or lexer, you might need to write a small novel to ensure that future readers understand what you did and why you did it.

            Show
            frossie Frossie Economou added a comment - FYI, here are the Perl core commit message guidelines, which I quite like (they are consistent with the above, but a bit more general) Commit message As you craft each patch you intend to submit to the Perl core, it's important to write a good commit message. This is especially important if your submission will consist of a series of commits. The first line of the commit message should be a short description without a period. It should be no longer than the subject line of an email, 50 characters being a good rule of thumb. A lot of Git tools (Gitweb, GitHub, git log --pretty=oneline, ...) will only display the first line (cut off at 50 characters) when presenting commit summaries. The commit message should include a description of the problem that the patch corrects or new functionality that the patch adds. As a general rule of thumb, your commit message should help a programmer who knows the Perl core quickly understand what you were trying to do, how you were trying to do it, and why the change matters to Perl. Why Your commit message should describe why the change you are making is important. When someone looks at your change in six months or six years, your intent should be clear. If you're deprecating a feature with the intent of later simplifying another bit of code, say so. If you're fixing a performance problem or adding a new feature to support some other bit of the core, mention that. What Your commit message should describe what part of the Perl core you're changing and what you expect your patch to do. How While it's not necessary for documentation changes, new tests or trivial patches, it's often worth explaining how your change works. Even if it's clear to you today, it may not be clear to a porter next month or next year. A commit message isn't intended to take the place of comments in your code. Commit messages should describe the change you made, while code comments should describe the current state of the code. If you've just implemented a new feature, complete with doc, tests and well-commented code, a brief commit message will often suffice. If, however, you've just changed a single character deep in the parser or lexer, you might need to write a small novel to ensure that future readers understand what you did and why you did it.
            Hide
            ktl Kian-Tat Lim added a comment -

            On 2014-09-16, the SAT recommended that these guidelines be adopted, along with the development of a training program for new and existing developers to teach them how to follow them.

            Show
            ktl Kian-Tat Lim added a comment - On 2014-09-16, the SAT recommended that these guidelines be adopted, along with the development of a training program for new and existing developers to teach them how to follow them.
            Hide
            mjuric Mario Juric added a comment -

            +1. Who will update the standards docs, and how (I.e, just links to the two offered documents, copy/paste their text, choose one, or write our own text based on these proposals?)

            Show
            mjuric Mario Juric added a comment - +1. Who will update the standards docs, and how (I.e, just links to the two offered documents, copy/paste their text, choose one, or write our own text based on these proposals?)
            Hide
            jkantor Jeff Kantor added a comment -

            +1

            Show
            jkantor Jeff Kantor added a comment - +1
            Hide
            ktl Kian-Tat Lim added a comment -

            Jeff and Mario have approved; we need to plan the implementation of this decision.

            Show
            ktl Kian-Tat Lim added a comment - Jeff and Mario have approved; we need to plan the implementation of this decision.
            Hide
            shaw Richard Shaw [X] (Inactive) added a comment -

            I'm confused: The description of this issue includes a link to a document about what constitutes a good git commit message. Frossie's comment (above) offers alternative text. Which content did the SAT approve?

            Show
            shaw Richard Shaw [X] (Inactive) added a comment - I'm confused: The description of this issue includes a link to a document about what constitutes a good git commit message. Frossie's comment (above) offers alternative text. Which content did the SAT approve?
            Hide
            ktl Kian-Tat Lim added a comment -

            The SAT did not discuss the specific language, just that such guidelines should exist along the lines of the above suggestions. The above guidelines are not mutually exclusive. I would say that the implementation plan should develop the specific language.

            Show
            ktl Kian-Tat Lim added a comment - The SAT did not discuss the specific language, just that such guidelines should exist along the lines of the above suggestions. The above guidelines are not mutually exclusive. I would say that the implementation plan should develop the specific language.
            Hide
            mjuric Mario Juric added a comment -
            Show
            mjuric Mario Juric added a comment - I added the necessary text to https://confluence.lsstcorp.org/display/LDMDG/Git+Commit+Best+Practices .

              People

              Assignee:
              ktl Kian-Tat Lim
              Reporter:
              mjuric Mario Juric
              Reviewers:
              Jeff Kantor, Mario Juric, Robyn Allsman [X] (Inactive)
              Watchers:
              Frossie Economou, Jeff Kantor, Kian-Tat Lim, Mario Juric, Richard Shaw [X] (Inactive)
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  Jenkins

                  No builds found.