Skip to content

Commit 06cd334

Browse files
linawolflinawolf
committed
[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 <noreply@anthropic.com> Signed-off-by: Lina Wolf
1 parent cb88081 commit 06cd334

8 files changed

Lines changed: 83 additions & 40 deletions

File tree

‎AGENTS.md‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,14 +27,13 @@ CONTRIBUTING.rst # how to contribute (issues, branching, PRs)
2727
`Documentation/Reference/ReStructuredText/Links/Anchors.rst`.
2828
6. **Validate before committing** — run `make test-docs`.
2929
7. **Never commit or push without being asked.**
30-
8. **Commit message**: short body explaining why, ending with
31-
`Assisted-by: <tool/model name> <contact>` and
32-
`Signed-off-by: <actual committer name>` trailers. This repo has only
33-
`main` (no LTS branches), so skip `Releases:`/`Resolves:`.
30+
8. **Commit message**: follow [Documentation/Advanced/CommitMessages.rst](Documentation/Advanced/CommitMessages.rst).
31+
This repo has only `main` (no LTS branches), so skip `Releases:`/`Resolves:`.
3432

3533
## References
3634

3735
- [CONTRIBUTING.rst](CONTRIBUTING.rst) — contribution workflow
36+
- [Documentation/Advanced/CommitMessages.rst](Documentation/Advanced/CommitMessages.rst) — commit message conventions
3837
- [Documentation/Advanced/ContentStyleGuide.rst](Documentation/Advanced/ContentStyleGuide.rst) — official writing style guide
3938
- [Documentation/Advanced/CodingGuidelines.rst](Documentation/Advanced/CodingGuidelines.rst) — reST formatting conventions
4039
- [Documentation/Reference/ReStructuredText/](Documentation/Reference/ReStructuredText/) — reST syntax reference (roles, directives, anchors, code blocks, ...)

‎Documentation/Advanced/CommitMessages.rst‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
.. include:: /Includes.rst.txt
2+
.. index:: ! Commit messages
3+
.. _commit-messages:
4+
5+
================
6+
Commit messages
7+
================
8+
9+
These conventions apply to every contribution, no matter whether you make
10+
your change :ref:`directly on GitHub <docs-contribute-github-method>` or
11+
:ref:`locally with Docker <docs-contribute-git-docker>`.
12+
13+
.. literalinclude:: /_CodeSnippets/_CommitMessageExample.txt
14+
:caption: Example commit message
15+
:language: text
16+
17+
If the change is related to a changelog entry, a Gerrit change, or an
18+
issue, mention it too:
19+
20+
.. literalinclude:: /_CodeSnippets/_ChangelogCommitMessageExample.txt
21+
:caption: Example commit message referencing a changelog issue
22+
:language: text
23+
24+
.. _commit-messages-format:
25+
26+
Format
27+
======
28+
29+
* Prefix the summary line with the type of change -- `[TASK]`,
30+
`[BUGFIX]` or `[FEATURE]` -- followed by a short, imperative summary.
31+
32+
* Explain *why* the change is needed in the body. The diff already shows
33+
what changed; the body should cover what the diff cannot.
34+
35+
* End with a `Signed-off-by: Your Name` trailer. Add an
36+
`Assisted-by: <tool/model name> <contact>` trailer too, if you used AI
37+
assistance for more than a basic spelling or grammar check.
38+
39+
* If the change is related to a changelog entry, mention that changelog
40+
entry. If it is related to a Gerrit change that had no changelog
41+
entry, mention that Gerrit change instead. If it is related to an
42+
issue, mention the issue number.
43+
44+
* If the manual has branches per version, add a line like
45+
`Releases: main, 14.3` to note which versions your change applies to
46+
(see :ref:`review policy <review-policy>`). Backporting to those
47+
branches then happens automatically (see :ref:`backport changes
48+
<backport-changes>`) -- manual backporting is only needed if the
49+
automatic backport hits a conflict or the content needs to be
50+
adjusted per version.

‎Documentation/Howto/EditLocal.rst‎

Lines changed: 7 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -98,29 +98,13 @@ the ability to experiment and preview your changes locally before submitting the
9898
9999
git commit -a
100100
101-
Prefix the summary line with the type of change -- `[TASK]`,
102-
`[BUGFIX]` or `[FEATURE]` -- followed by a short, imperative summary,
103-
for example `[TASK] Document anchor persistence rule`.
104-
105-
Explain *why* the change is needed in the body. The diff already shows
106-
what changed; the body should cover what the diff cannot.
107-
108-
End with a `Signed-off-by: Your Name` trailer. If you used AI assistance
109-
for more than a basic spelling or grammar check, add an
110-
`Assisted-by: <tool/model name> <contact>` trailer as well.
111-
112-
If the change is related to a changelog entry, mention that changelog
113-
entry. If it is related to a Gerrit change that had no changelog entry,
114-
mention that Gerrit change instead. If it is related to an issue,
115-
mention the issue number. See :ref:`howto-update-docs-commit-messages`
116-
for an example.
117-
118-
If the manual has branches per version, add a line like
119-
`Releases: main, 14.3` to note which versions your change applies to
120-
(see :ref:`review-policy`). Backporting to those branches then happens
121-
automatically (see :ref:`backport-changes`) -- manual backporting is
122-
only needed if the automatic backport hits a conflict or the content
123-
needs to be adjusted per version.
101+
See :ref:`commit message conventions <commit-messages>` for how to
102+
phrase the summary line and body, which trailers to add, and how to
103+
reference related changes, for example:
104+
105+
.. literalinclude:: /_CodeSnippets/_CommitMessageExample.txt
106+
:caption: Example commit message
107+
:language: text
124108

125109
9. Push changes
126110

‎Documentation/Howto/EditOnGithub.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,9 @@ Workflow #1: "Edit on GitHub"
6969
8. Finalize your changes:
7070

7171
When you are ready, scroll down to the bottom of the page. Add
72-
a short (but meaningful) description that outlines the changes you have made and click "Propose
73-
file change"
72+
a commit message that outlines the changes you have made -- see
73+
:ref:`commit message conventions <commit-messages>` -- and click
74+
"Propose file change"
7475

7576
.. image:: /_Images/github-propose-file-changes.png
7677
:class: with-border with-shadow

‎Documentation/Maintainers/BackportChanges.rst‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -37,8 +37,9 @@ Leave a hint about which versions you have tested, for example:
3737
main. Could someone verify this please?
3838
3939
Releases: main, 14.3, 13.4
40-
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
41-
Signed-off-by: Jane Doe
40+
41+
See :ref:`commit message conventions <commit-messages>` for the full
42+
picture.
4243

4344
The backporting itself will be done by the maintainers of the Documentation Team.
4445
Sometimes automatic backporting is not possible due to changes in the documentation

‎Documentation/Maintainers/Changelog.rst‎

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -28,17 +28,12 @@ Commit messages
2828
===============
2929

3030
All changes that are related to such an issue should contain a reference in
31-
their commit message to the issue, for example
31+
their commit message to the issue (see :ref:`commit message conventions
32+
<commit-messages>` for the full picture), for example:
3233

33-
.. code-block:: text
34+
.. literalinclude:: /_CodeSnippets/_ChangelogCommitMessageExample.txt
3435
:caption: Example commit message
35-
36-
[FEATURE] Add ApplicationContext to TypoScript data
37-
38-
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
39-
Releases: main
40-
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
41-
Signed-off-by: Jane Doe
36+
:language: text
4237

4338
.. index::
4439
Documentation; Deprecations

‎Documentation/_CodeSnippets/_ChangelogCommitMessageExample.txt‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[FEATURE] Add ApplicationContext to TypoScript data
2+
3+
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
4+
Releases: main
5+
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
6+
Signed-off-by: Jane Doe

‎Documentation/_CodeSnippets/_CommitMessageExample.txt‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
[TASK] Add missing alt text for screenshots
2+
3+
Screen reader users could not tell what the two new screenshots showed.
4+
Add descriptive alt text to both.
5+
6+
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
7+
Signed-off-by: Jane Doe

0 commit comments

Comments
 (0)