Skip to content

Commit ab28c93

Browse files
[TASK] Document commit message conventions for contributors (#548)
* [TASK] Document commit message conventions for contributors EditLocal.rst only said "write a short, meaningful commit message." Document the actual convention: [TASK]/[BUGFIX]/[FEATURE] prefix, a why-focused body, Signed-off-by/Assisted-by trailers, references to related changelog entries/Gerrit changes/issues, and how Releases: lines relate to automatic backporting. Also refreshed the Releases: examples in BackportChanges.rst and ReviewPolicy.rst from 12.4/11.5 to 14.3/13.4. Verified with the full Docker render pipeline. Assisted-by: Claude Sonnet 5 <noreply@anthropic.com> Signed-off-by: Lina Wolf * [TASK] Language checks Releases:main --------- Signed-off-by: Lina Wolf Co-authored-by: Sarah McCarthy <sarahmccarthy123@yahoo.com>
1 parent 06469b3 commit ab28c93

4 files changed

Lines changed: 32 additions & 5 deletions

File tree

Documentation/Advanced/ReviewPolicy.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ the following:
2929
* Please ensure that your Pull Request is **made against the appropriate
3030
version of the documentation**, usually against the `main` branch. If the
3131
changes you propose apply to specific versions of the documentation,
32-
you can add a line like `Releases: main, 12.4, 11.5` to note any
32+
you can add a line like `Releases: main, 14.3, 13.4` to note any
3333
Git branch that your change would apply to. If you are unsure,
3434
our maintainers will take care of it - this is just a step to make
3535
their work easier.

Documentation/Howto/EditLocal.rst

Lines changed: 24 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -98,7 +98,30 @@ the ability to experiment and preview your changes locally before submitting the
9898
9999
git commit -a
100100
101-
Write a short, meaningful commit message describing what changes you have made.
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 of the commit. The diff
106+
already shows what has changed. The commit body should cover what the diff
107+
cannot.
108+
109+
End with a `Signed-off-by: Your Name` trailer. If you have used AI assistance
110+
for more than basic spelling or grammar checks, add an
111+
`Assisted-by: <tool/model name> <contact>` trailer as well.
112+
113+
If the change is related to a changelog entry, mention the changelog
114+
entry. If it is related to a Gerrit change that does not have a changelog
115+
entry, mention the Gerrit change instead. If it is related to an issue,
116+
mention the issue number. See :ref:`howto-update-docs-commit-messages`
117+
for an example.
118+
119+
If the manual has version branches, add a line like
120+
`Releases: main, 14.3` to note which version branches your change applies to
121+
(see :ref:`review-policy`). Backporting to these branches will then happen
122+
automatically (see :ref:`backport-changes`). Manual backporting is
123+
only needed if the automatic backport hits a conflict or the content
124+
needs to be changed for a version.
102125

103126
9. Push changes
104127

Documentation/Maintainers/BackportChanges.rst

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ commit message (as done in the Core):
1313

1414
.. code-block:: text
1515
16-
Releases: main, 12.4
16+
Releases: main, 14.3
1717
1818
However, this is not enforced and not always done. In any case, it is
1919
up to the user merging a PR to decide how far the changes are to be
@@ -33,10 +33,12 @@ Leave a hint about which versions you have tested, for example:
3333

3434
.. code-block:: text
3535
36-
Verified this on 12.4 and 11.5, I suspect it will also still be the case on
36+
Verified this on 14.3 and 13.4, I suspect it will also still be the case on
3737
main. Could someone verify this please?
3838
39-
Releases: main, 12.4, 11.5
39+
Releases: main, 14.3, 13.4
40+
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
41+
Signed-off-by: Jane Doe
4042
4143
The backporting itself will be done by the maintainers of the Documentation Team.
4244
Sometimes automatic backporting is not possible due to changes in the documentation

Documentation/Maintainers/Changelog.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,8 @@ their commit message to the issue, for example
3737
3838
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/790
3939
Releases: main
40+
Assisted-by: Claude Sonnet 5 <noreply@anthropic.com>
41+
Signed-off-by: Jane Doe
4042
4143
.. index::
4244
Documentation; Deprecations

0 commit comments

Comments
 (0)