Changeset d144cf0 in rtems-docs

12/14/22 18:05:40 (3 months ago)
Joel Sherrill <joel@…>
Joel Sherrill <joel@…> (12/14/22 18:05:40)
Joel Sherrill <joel@…> (12/14/22 22:46:17)

eng/vc-users.rst: Add commit message guidance

Closes #4275.

1 edited


  • eng/vc-users.rst

    r031cb12 rd144cf0  
    423423into yours can become messy.
    425 Accessing a developer's repository
     425Accessing a Developer's Repository
    430430development work shared there.
     432Commit Message Guidance
     435The commit message associated with a change to any software project
     436is of critical importance. It is the explanation of the change and the
     437rationale for it. Future users looing back through the project history
     438will rely on it. Even the author of the change will likely rely on it
     439once they have forgotten the details of the change. It is important to
     440make the message useful. Here are some guidelines followed by the RTEMS
     441Project to help improve the quality of our commit messages.
     443* When committing a change the first line is a summary. Please make it short
     444  while hinting at the nature of the change. You can discuses the change
     445  if you wish in a ticket that has a PR number which can be referenced in
     446  the commit message. After the first line, leave an empty line and add
     447  whatever required details you feel are needed.
     449* Patches should be as single purpose as possible. This is reflected in
     450  the first line summary message. If you find yourself writing something
     451  like "Fixed X and Y", "Updated A and B", or similar, then evaluate
     452  whether the patch should really be a patch series rather than a single
     453  larger patch.
     455* Format the commit message so it is readable and clear. If you have
     456  specific points related to the change make them with separate paragraphs
     457  and if you wish you can optionally uses a `-` marker with suitable
     458  indents and alignment to aid readability.
     460* Limit the line length to less than 80 characters
     462* Please use a real name with a valid email address. Please do not use
     463  pseudonyms or provide anonymous contributions.
     465* Please do not use terms such as "Fix bug", "With this change it
     466  works", or "Bump hash". If you fix a bug please state the nature of the
     467  bug and why this change fixes it. If a change makes something work then
     468  detail the reason. You do not need to explain the change line by line
     469  as the commits diff and associated ticket will.
     471* If you change the formatting of source code in a repository please
     472  make that a separate patch and use "Formatting changes only" on the first
     473  line. Please indicate the reason or process. For example to "Conforming
     474  to code standing", "Reverting to upstream format", "Result of automatic
     475  formatting".
     477* Similarly, if addressing a spelling, grammar, or Doxygen issue, please
     478  put that in a commit by itself separate from technical changes.
     480An example commit message:
     482.. code-block:: shell
     484  test/change: Test message on formatting of commits
     486  - Shows a simple single first line
     488  - Has an empty second line
     490  - Shows the specifics of adding separate points in the commit message as
     491    separate paragraphs. It also shows a `-` separator and multilines
     492    that are less than the 80 character width
     494  - Show a ticket update and close
     496  Updates #9876
     497  Closes #8765
     499The first line generally starts with a file or directory name which
     500indicates the area in RTEMS to which the commit applies. For a patch
     501series which impacts multiple BSPs, it is common to put each BSP into
     502a separate patch. This improves the quality and specificity of the
     503commit messages.
    432505Creating a Patch
    433 ----------------
    435 Before submitting a patch read about `Contributing
    436 <>`_ to RTEMS and the
    437 `Commit Message <>`_
    438 formatting we require.
     508Before submitting a patch, please read `Commit Message Guidance`_ to
     509become familiar with the commit message formatting we require.
    440511The recommended way to create a patch is to branch the Git repository master
Note: See TracChangeset for help on using the changeset viewer.