From 7b1b19df8a8687b9abc9df245d36a8b23a787129 Mon Sep 17 00:00:00 2001 From: "lina.wolf" Date: Mon, 24 Aug 2026 14:33:57 +0200 Subject: [PATCH] [TASK] Consolidate commit message conventions into one page The convention was documented in full in EditLocal.rst and restated with drift in Changelog.rst, BackportChanges.rst, and AGENTS.md; the GitHub-editing workflow didn't mention it at all. Add Documentation/Advanced/CommitMessages.rst as the single source of truth, leading with examples kept in Documentation/_CodeSnippets/ and pulled in via literalinclude where needed. Other pages now link to it instead of restating it. Verified with the full Docker render pipeline. Assisted-by: Claude Sonnet 5 Signed-off-by: Lina Wolf --- AGENTS.md | 7 ++- Documentation/Advanced/CommitMessages.rst | 50 +++++++++++++++++++ Documentation/Howto/EditLocal.rst | 31 +++--------- Documentation/Howto/EditOnGithub.rst | 5 +- Documentation/Maintainers/BackportChanges.rst | 5 +- Documentation/Maintainers/Changelog.rst | 13 ++--- .../_ChangelogCommitMessageExample.txt | 6 +++ .../_CodeSnippets/_CommitMessageExample.txt | 7 +++ 8 files changed, 83 insertions(+), 41 deletions(-) create mode 100644 Documentation/Advanced/CommitMessages.rst create mode 100644 Documentation/_CodeSnippets/_ChangelogCommitMessageExample.txt create mode 100644 Documentation/_CodeSnippets/_CommitMessageExample.txt diff --git a/AGENTS.md b/AGENTS.md index 0c11dd6e..3663a700 100644 --- a/AGENTS.md +++ b/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: ` and - `Signed-off-by: ` 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, ...) diff --git a/Documentation/Advanced/CommitMessages.rst b/Documentation/Advanced/CommitMessages.rst new file mode 100644 index 00000000..83e949bd --- /dev/null +++ b/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 ` or +:ref:`locally with 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: ` 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 `). Backporting to those + branches then happens automatically (see :ref:`backport changes + `) -- manual backporting is only needed if the + automatic backport hits a conflict or the content needs to be + adjusted per version. diff --git a/Documentation/Howto/EditLocal.rst b/Documentation/Howto/EditLocal.rst index c94541eb..6906a45e 100644 --- a/Documentation/Howto/EditLocal.rst +++ b/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: ` 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 ` 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 diff --git a/Documentation/Howto/EditOnGithub.rst b/Documentation/Howto/EditOnGithub.rst index f4c04351..9a8b477a 100644 --- a/Documentation/Howto/EditOnGithub.rst +++ b/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 ` -- and click + "Propose file change" .. image:: /_Images/github-propose-file-changes.png :class: with-border with-shadow diff --git a/Documentation/Maintainers/BackportChanges.rst b/Documentation/Maintainers/BackportChanges.rst index d5fba0aa..146da039 100644 --- a/Documentation/Maintainers/BackportChanges.rst +++ b/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 - Signed-off-by: Jane Doe + +See :ref:`commit message conventions ` 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 diff --git a/Documentation/Maintainers/Changelog.rst b/Documentation/Maintainers/Changelog.rst index ab28aab4..a4bada18 100644 --- a/Documentation/Maintainers/Changelog.rst +++ b/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 +` 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 - Signed-off-by: Jane Doe + :language: text .. index:: Documentation; Deprecations diff --git a/Documentation/_CodeSnippets/_ChangelogCommitMessageExample.txt b/Documentation/_CodeSnippets/_ChangelogCommitMessageExample.txt new file mode 100644 index 00000000..2f819330 --- /dev/null +++ b/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 +Signed-off-by: Jane Doe diff --git a/Documentation/_CodeSnippets/_CommitMessageExample.txt b/Documentation/_CodeSnippets/_CommitMessageExample.txt new file mode 100644 index 00000000..3aea9a43 --- /dev/null +++ b/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 +Signed-off-by: Jane Doe