Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[TASK] Add info for long links in commitmsg and add refs #361

Merged
merged 3 commits into from
Aug 27, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
36 changes: 36 additions & 0 deletions Documentation/Appendix/CommitMessage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -170,6 +170,42 @@ 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

Resolves: #12346
Related: #12340
Releases: main, 12.4
Change-Id: I<some string generated by the git commit-msg hook>

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