Skip to content

Commit

Permalink
[TASK] Add info for long links in commitmsg and add refs
Browse files Browse the repository at this point in the history
The quickstart guide was missing a pointer to proper formatting
of the commit message.

Also, the section on the commit message is now enhanced to
describe when and how long lines are allowed, with examples
for hyperlinks.
  • Loading branch information
garvinhicking committed Aug 27, 2024
1 parent b834bd1 commit 6e01d37
Show file tree
Hide file tree
Showing 4 changed files with 35 additions and 1 deletion.
1 change: 1 addition & 0 deletions Documentation/Appendix/CommitHook.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@ a Change-Id on your own, the result will be chaos.

Apart from that the hook will check your commit message for logical errors like missing keywords, Resolves lines etc.
For detailed information on the format of a commit message, :ref:`click here <commitmessage>`.
This also describes cases in which you might exceed the line length of 72 characters (hyperlinks).

If the commit-msg hook finds errors in your commit-msg, you can try again, by amending to the commit::

Expand Down
31 changes: 31 additions & 0 deletions Documentation/Appendix/CommitMessage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,37 @@ Here you can go into detail about the how and why of the change. It should be br

- Wrap the lines after 72 characters manually

.. _commitmessage-links:
Inserting links / long lines
----------------------------

Sometimes you must insert long links that exceed the line length of 72 characters.

In that case, it is ok to have these long lines - because inserting linebreaks
would make the link invalid. You can ignore warnings of possible CGL checks,
or (temporarily) disable your GIT commit hook check for this specific warning.

It is best practice to use placeholders for links and then group used links
at the end in your commit message, like this:

.. code-block:: none
[BUGFIX] Link some long links
In [1] is is documented, that something is not wrong. But
in reality [2] properly indicates, this is indeed right.
So we follow the advice of [3][4] and make things better.
[1] https://example.com/a/very/very/long-link/because/it/is/really-needed-I-mean-it-its-long-but-okay
[2] https://example.com/this/is/short/but/also/nice
[3] https://example.com/snafu
[4] https://example.com/mostlyharmless
This is no specifically parsed syntax, the `[number]` formatting is
just common plaintext formatting.


Relationships
-------------

Expand Down
2 changes: 1 addition & 1 deletion Documentation/CheatSheets/Git.rst
Original file line number Diff line number Diff line change
Expand Up @@ -235,7 +235,7 @@ Other keywords:
* subject < 52 chars (if possible, otherwise <= 72)
* other lines <= 72 chars

* hyperlinks with > 72 chars are allowed when required (:ref:`<commitmessage-links>`)

Workflow - Undoing / fixing things
==================================
Expand Down
2 changes: 2 additions & 0 deletions Documentation/Quickstart/6-Patch.rst
Original file line number Diff line number Diff line change
Expand Up @@ -119,6 +119,8 @@ Now with this example in mind, we have two modified files that we want to commit
Releases: main
Close your editor with saving the commit message.
For proper formatting and wording of a commit message, please read the
details in :ref:`commitmessage`.
5. Push to Git repository
Expand Down

0 comments on commit 6e01d37

Please sign in to comment.