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