diff --git a/Documentation/Appendix/CommitHook.rst b/Documentation/Appendix/CommitHook.rst index a68b22e2..eb3297b1 100644 --- a/Documentation/Appendix/CommitHook.rst +++ b/Documentation/Appendix/CommitHook.rst @@ -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 `. +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:: diff --git a/Documentation/Appendix/CommitMessage.rst b/Documentation/Appendix/CommitMessage.rst index 2594734c..7d48d601 100644 --- a/Documentation/Appendix/CommitMessage.rst +++ b/Documentation/Appendix/CommitMessage.rst @@ -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 + +This is no specifically parsed syntax, the `[number]` formatting is +just common plaintext formatting. + + Relationships ------------- diff --git a/Documentation/CheatSheets/Git.rst b/Documentation/CheatSheets/Git.rst index 8d00ff15..b8758747 100644 --- a/Documentation/CheatSheets/Git.rst +++ b/Documentation/CheatSheets/Git.rst @@ -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:``) Workflow - Undoing / fixing things ================================== diff --git a/Documentation/Quickstart/6-Patch.rst b/Documentation/Quickstart/6-Patch.rst index 863edcc8..af463eae 100644 --- a/Documentation/Quickstart/6-Patch.rst +++ b/Documentation/Quickstart/6-Patch.rst @@ -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