Add changelog entry guidance and agreed upon standards for new contributors (#990)

csutherl · csutherl · commit 8c39ca8cfef7 · 2026-04-14T08:26:06.000-04:00
diff --git 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
@@ -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
