This is an automated email from the ASF dual-hosted git repository.
csutherl pushed a commit to branch 10.1.x
in repository https://gitbox.apache.org/repos/asf/tomcat.git
The following commit(s) were added to refs/heads/10.1.x by this push:
new 8c39ca8cfe Add changelog entry guidance and agreed upon standards for
new contributors (#990)
8c39ca8cfe is described below
commit 8c39ca8cfef7b056fd48b8a8445ec20eaa5d7b0d
Author: Coty Sutherland <[email protected]>
AuthorDate: Tue Apr 14 08:24:27 2026 -0400
Add changelog entry guidance and agreed upon standards for new contributors
(#990)
---
CONTRIBUTING.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++
webapps/docs/changelog.xml | 3 +++
2 files changed, 64 insertions(+)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d47fe8359b..08537bca1d 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -157,6 +157,67 @@ source (.txt, .xml)
* Java source: { at end of line, 4 space indents
* XML source: 2 space indents
+## Changelog Entries
+
+Every code change that affects functionality, behavior, or user-visible
features should have a corresponding entry in `webapps/docs/changelog.xml`.
+
+### When Changelog Entries Are Needed
+
+Add a changelog entry for:
+- New features or APIs
+- Bug fixes
+- Changes to defaults or existing behavior
+- Removals or deprecations
+- Significant refactoring that affects performance or behavior
+- Documentation updates to public APIs
+
+Skip changelog entries for:
+- Test-only changes (unless fixing a test infrastructure issue)
+- Build script maintenance
+- Internal code cleanup with no user impact
+
+### Entry Types
+
+Use the appropriate XML element based on the nature of your change:
+
+- `<add>` - New features, APIs, or capabilities. Start with "Add" or
"Implement".
+ Example: `Add support for Jakarta EE 12 XML schemas.`
+
+- `<update>` - Changes to existing features, defaults, or removals. Start with
"Change", "Remove", or "Update".
+ Example: `Change the default for encodedSolidusHandling from decode to
reject.`
+
+- `<fix>` - Bug fixes. Start with "Fix". Include `<bug>NUMBER</bug>` if
applicable.
+ Example: `<bug>70000</bug>: Fix duplication of special headers in the
response after commit.`
+
+- `<scode>` - Internal refactoring or code structure changes. Explain the
benefit, not just the change.
+ Example: `Refactor generation of the remote user element in the access log
to remove unnecessary code.`
+
+- `<docs>` - Documentation-only updates (Javadoc, configuration docs).
+ Example: `Add Javadoc for the Common Annotations API implementation.`
+
+### Style and Formatting
+
+- Write in present tense, imperative mood ("Add support" not "Added support")
+- Keep entries concise (1-3 sentences)
+- Use `<code>` tags for class names, method names, and configuration attributes
+- Use `<bug>NUMBER</bug>` for Bugzilla references
+- For default changes, show before -> after: "from `false` to `true`"
+- End with attribution in parentheses: `(username)`
+- For community patches: "Patch submitted by Name. (committer)"
+
+### Subsection Placement
+
+Place entries in the appropriate subsection following this order:
+General, Catalina, Coyote, Jasper, Cluster, WebSocket, Web applications,
Extras, Tribes, jdbc-pool, Other
+
+### Common Pitfalls to Avoid
+
+- Don't use past tense ("Fixed" -> use "Fix")
+- Don't omit `<code>` tags for technical terms
+- Don't forget attribution at the end
+- Don't be vague ("Fix bug" -> "Fix NPE when processing empty request headers")
+- Don't include implementation details unless relevant to users
+
## Did we miss something?
Have you reviewed this guide and found it lacking? Or are you confused about
diff --git a/webapps/docs/changelog.xml b/webapps/docs/changelog.xml
index 7693aa4f31..804f2b0f54 100644
--- a/webapps/docs/changelog.xml
+++ b/webapps/docs/changelog.xml
@@ -90,6 +90,9 @@
<body>
<!--
+ For guidance on writing changelog entries, see the "Changelog Entries"
+ section in CONTRIBUTING.md.
+
Subsection ordering:
General, Catalina, Coyote, Jasper, Cluster, WebSocket, Web applications,
Extras, Tribes, jdbc-pool, Other
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
