[TASK] Consolidate commit message conventions into one page

AGENTS.md

@@ -27,14 +27,13 @@ CONTRIBUTING.rst                 # how to contribute (issues, branching, PRs)
    `Documentation/Reference/ReStructuredText/Links/Anchors.rst`.
 6. **Validate before committing** — run `make test-docs`.
 7. **Never commit or push without being asked.**
-8. **Commit message**: short body explaining why, ending with
-   `Assisted-by: <tool/model name> <contact>` and
-   `Signed-off-by: <actual committer name>` trailers. This repo has only
-   `main` (no LTS branches), so skip `Releases:`/`Resolves:`.
+8. **Commit message**: follow [Documentation/Advanced/CommitMessages.rst](Documentation/Advanced/CommitMessages.rst).
+   This repo has only `main` (no LTS branches), so skip `Releases:`/`Resolves:`.
 
 ## References
 
 - [CONTRIBUTING.rst](CONTRIBUTING.rst) — contribution workflow
+- [Documentation/Advanced/CommitMessages.rst](Documentation/Advanced/CommitMessages.rst) — commit message conventions
 - [Documentation/Advanced/ContentStyleGuide.rst](Documentation/Advanced/ContentStyleGuide.rst) — official writing style guide
 - [Documentation/Advanced/CodingGuidelines.rst](Documentation/Advanced/CodingGuidelines.rst) — reST formatting conventions
 - [Documentation/Reference/ReStructuredText/](Documentation/Reference/ReStructuredText/) — reST syntax reference (roles, directives, anchors, code blocks, ...)

Documentation/Advanced/CommitMessages.rst

@@ -0,0 +1,50 @@
+..  include:: /Includes.rst.txt
+..  index:: ! Commit messages
+..  _commit-messages:
+
+================
+Commit messages
+================
+
+These conventions apply to every contribution, no matter whether you make
+your change :ref:`directly on GitHub <docs-contribute-github-method>` or
+:ref:`locally with Docker <docs-contribute-git-docker>`.
+
+..  literalinclude:: /_CodeSnippets/_CommitMessageExample.txt
+    :caption: Example commit message
+    :language: text
+
+If the change is related to a changelog entry, a Gerrit change, or an
+issue, mention it too:
+
+..  literalinclude:: /_CodeSnippets/_ChangelogCommitMessageExample.txt
+    :caption: Example commit message referencing a changelog issue
+    :language: text
+
+..  _commit-messages-format:
+
+Format
+======
+
+*   Prefix the summary line with the type of change -- `[TASK]`,
+    `[BUGFIX]` or `[FEATURE]` -- followed by a short, imperative summary.
+
+*   Explain *why* the change is needed in the body. The diff already shows
+    what changed; the body should cover what the diff cannot.
+
+*   End with a `Signed-off-by: Your Name` trailer. Add an
+    `Assisted-by: <tool/model name> <contact>` trailer too, if you used AI
+    assistance for more than a basic spelling or grammar check.
+
+*   If the change is related to a changelog entry, mention that changelog
+    entry. If it is related to a Gerrit change that had no changelog
+    entry, mention that Gerrit change instead. If it is related to an
+    issue, mention the issue number.
+
+*   If the manual has branches per version, add a line like
+    `Releases: main, 14.3` to note which versions your change applies to
+    (see :ref:`review policy <review-policy>`). Backporting to those
+    branches then happens automatically (see :ref:`backport changes
+    <backport-changes>`) -- manual backporting is only needed if the
+    automatic backport hits a conflict or the content needs to be
+    adjusted per version.

Documentation/Howto/EditLocal.rst

@@ -98,30 +98,13 @@ the ability to experiment and preview your changes locally before submitting the
 
         git commit -a
 
-    Prefix the summary line with the type of change -- `[TASK]`,
-    `[BUGFIX]` or `[FEATURE]` -- followed by a short, imperative summary,
-    for example `[TASK] Document anchor persistence rule`.
-
-    Explain *why* the change is needed in the body of the commit. The diff
-    already shows what has changed. The commit body should cover what the diff
-    cannot.
-
-    End with a `Signed-off-by: Your Name` trailer. If you have used AI assistance
-    for more than basic spelling or grammar checks, add an
-    `Assisted-by: <tool/model name> <contact>` trailer as well.
-
-    If the change is related to a changelog entry, mention the changelog
-    entry. If it is related to a Gerrit change that does not have a changelog
-    entry, mention the Gerrit change instead. If it is related to an issue,
-    mention the issue number. See :ref:`howto-update-docs-commit-messages`
-    for an example.
-
-    If the manual has version branches, add a line like
-    `Releases: main, 14.3` to note which version branches your change applies to
-    (see :ref:`review-policy`). Backporting to these branches will then happen
-    automatically (see :ref:`backport-changes`). Manual backporting is
-    only needed if the automatic backport hits a conflict or the content
-    needs to be changed for a version.
+    See :ref:`commit message conventions <commit-messages>` for how to
+    phrase the summary line and body, which trailers to add, and how to
+    reference related changes, for example:
+
+    ..  literalinclude:: /_CodeSnippets/_CommitMessageExample.txt
+        :caption: Example commit message
+        :language: text
 
 9.  Push changes
 

Documentation/Howto/EditOnGithub.rst

@@ -69,8 +69,9 @@ Workflow #1: "Edit on GitHub"
 8.  Finalize your changes:
 
     When you are ready, scroll down to the bottom of the page. Add
-    a short (but meaningful) description that outlines the changes you have made and click "Propose
-    file change"
+    a commit message that outlines the changes you have made -- see
+    :ref:`commit message conventions <commit-messages>` -- and click
+    "Propose file change"
 
     ..  image:: /_Images/github-propose-file-changes.png
         :class: with-border with-shadow

Documentation/Maintainers/BackportChanges.rst

@@ -37,8 +37,9 @@ Leave a hint about which versions you have tested, for example:
     main. Could someone verify this please?
 
     Releases: main, 14.3, 13.4
-    Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
-    Signed-off-by: Jane Doe
+
+See :ref:`commit message conventions <commit-messages>` for the full
+picture.
 
 The backporting itself will be done by the maintainers of the Documentation Team.
 Sometimes automatic backporting is not possible due to changes in the documentation

Documentation/Maintainers/Changelog.rst

@@ -28,17 +28,12 @@ Commit messages
 ===============
 
 All changes that are related to such an issue should contain a reference in
-their commit message to the issue, for example
+their commit message to the issue (see :ref:`commit message conventions
+<commit-messages>` for the full picture), for example:
 
-..  code-block:: text
+..  literalinclude:: /_CodeSnippets/_ChangelogCommitMessageExample.txt
     :caption: Example commit message
-
-    [FEATURE] Add ApplicationContext to TypoScript data
-
-    Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
-    Releases: main
-    Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
-    Signed-off-by: Jane Doe
+    :language: text
 
 ..  index::
     Documentation; Deprecations

Documentation/_CodeSnippets/_ChangelogCommitMessageExample.txt

@@ -0,0 +1,6 @@
+[FEATURE] Add ApplicationContext to TypoScript data
+
+Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
+Releases: main
+Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
+Signed-off-by: Jane Doe

Documentation/_CodeSnippets/_CommitMessageExample.txt

@@ -0,0 +1,7 @@
+[TASK] Add missing alt text for screenshots
+
+Screen reader users could not tell what the two new screenshots showed.
+Add descriptive alt text to both.
+
+Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
+Signed-off-by: Jane Doe