ramanathan1504 commented on PR #488:
URL: https://github.com/apache/logging-parent/pull/488#issuecomment-5049423093
@ppkarwasz
I just have a few minor suggestions and questions for you to consider:
### `build-lifecycle.adoc`
* **Under `=== Code style`:** You mention setting a `.gitattributes` file.
Since developers might not know exactly what rules to put in it, would it be
worth adding a 1-2 line snippet they can copy, or a link to a standard Apache
Logging `.gitattributes` reference file?
* **Under `=== Changelog validation`:** You link to
`{logging-services-url}/xml/ns/#log4j-changelog`. I assume
`{logging-services-url}` is defined globally in the site's playbook, but just
double-checking to make sure it won't render as broken text since it isn't
defined in the header of this specific file!
* **Under `Optional lifecycle extensions > -Prelease`:** It notes that this
profile *"enforces that neither the project version nor any of its dependencies
is a SNAPSHOT."* You might want to quickly clarify if this applies strictly to
external dependencies, as multi-module builds usually have SNAPSHOT versions of
sibling modules during the build process (though Maven handles this
transparently, so leaving it as-is is probably fine too).
### `troubleshooting.adoc`
* **Hardcoded Version Numbers:** Throughout the file, you use concrete
versions like `2.27.0-SNAPSHOT`, `2.26.1`, and `2.20.2`. While this is good for
readability because it perfectly matches the terminal output snippet, these
specific numbers will eventually look outdated.
* *Suggestion:* Should we replace them with generic placeholders (like
`<major>.<minor>.<patch>` or `x.y.z`)? Alternatively, if we want to keep the
concrete numbers for easier reading, maybe we just add a small note like:
*"Note: versions like 2.27.0 are used here purely as examples"* so it ages
better?
* **Under `=== MINOR` (Formatting consistency):** In step 3, you use
`**not**` (double asterisks), but you used `*not*` (single asterisks) in the
`MICRO` section above. I recommend changing it to `*not*` just for AsciiDoc
consistency.
* **Under `=== MINOR` (Step 2 - Changelog):** Step 1 mentions bumping the
`<revision>` property to a new minor version (e.g., `2.27.0-SNAPSHOT`). Does
the developer also need to create a new changelog directory like
`src/changelog/.2.27.x/` instead of the old patch one? If the
`log4j-changelog-maven-plugin` expects the directory to match, it might be
worth explicitly stating that they should create the new minor release
directory here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
