From 0401a9423baa41b899ad8ade2e6869ea302224d9 Mon Sep 17 00:00:00 2001 From: Garvin Hicking Date: Tue, 27 Aug 2024 14:45:02 +0200 Subject: [PATCH] [TASK] Add info for long links in commitmsg and add refs (#361) * [TASK] Add info for long links in commitmsg and add refs 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. * [TASK] Make commit message complete with Resolves/Releases/Change-ID * [BUGFIX] Fix commit message appendix --- Documentation/Appendix/CommitHook.rst | 1 + Documentation/Appendix/CommitMessage.rst | 36 ++++++++++++++++++++++++ Documentation/CheatSheets/Git.rst | 2 +- Documentation/Quickstart/6-Patch.rst | 2 ++ 4 files changed, 40 insertions(+), 1 deletion(-) 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