Hi Volkan, On 8.07.2025 10:44, Volkan Yazıcı wrote: > I see that the most recent VOTE email misses ticket IDs, making it > cumbersome to access associated PRs. I can see the Discussion linked, but > that is not what I am asking for. > > Can we share the Issue/PR IDs in the VOTE emails, please?
I appreciate you bringing this up. Since you find it helpful, and I have no strong objections, I will include the changelog in future VOTE emails. That said, I’d like to use this opportunity to open a broader discussion on how we handle and duplicate release-related content across various channels. Specifically, I’d like to clarify our approach regarding the following: 1. **Release Notes** These are the curated summaries we write in `.release-notes.adoc.ftl` files. In my view, release notes are essential and should appear in all of the following: * Our website. * The VOTE email (so PMC members can easily see what changed). * The `annou...@apache.org` email (while not universally practiced, many projects include release notes in the announcement [3]). * GitHub Releases, since Dependabot pulls release notes from there. While some projects (e.g., JUnit) only link to their website in their GitHub Releases, I believe inlining our release notes is worthwhile. Note that—except for our website, which uses the original AsciiDoc format—all other channels require manual conversion to plain text or Markdown, particularly for hyperlinks. 2. **Changelog** By *changelog*, I mean a complete list of changes relevant to users—excluding things like test or Javadoc updates, which don’t affect user-facing behavior. I suggest we **do not** replicate the changelog in too many places. Instead: * Keep it on the website. * Include it in the VOTE email (useful for developers, even if a bit noisy). * Link to it in the announcement email, rather than embedding it. For GitHub/Dependabot purposes, we have two options: 1. Add a link to the website in our GitHub Releases. 2. Add a `CHANGELOG.md` file in the repo with the latest entries, and link to the website for older ones. GitHub looks for keywords like `changelog`, `news`, `changes`, `history`, etc., to identify changelog files. 3. **Commits** GitHub/Dependabot uses the three-dot comparison between release tags, e.g.: https://github.com/apache/logging-log4j2/compare/rel%2F2.24.3...rel%2F2.25.0 Due to the way I’ve been creating patch releases—by branching off the previous release tag and cherry-picking fixes from `2.x`—the merge base between patch and minor releases is often far back, usually before the previous minor. As a result, the commit list in these comparisons includes too many unrelated changes. This might be worth revisiting. Should we consider a different strategy for patch releases to improve clarity in these diffs? **Context and Motivation** I’ve been working on enhancing `dependabot/fetch-metadata` to use it in our Dependabot workflow, which led me to explore how release information is generated by the bot. To help users decide whether a dependency update is relevant (e.g., for a Log4j patch), we should aim to expose structured and clear metadata. For a quick preview on what data Dependabot gathers, see ppkarwasz/logging-log4j2#566[2]. The sources of the gathered data are: 1. For the "Release notes" section: GitHub Releases. 2. For the "Changelog" section: files in the project repository. 3. For the "Commits" section: the three-dot GitHub comparison. Looking forward to your thoughts. Best wishes, Piotr [1] https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-comparing-branches-in-pull-requests#about-three-dot-comparison-on-github [2] https://github.com/ppkarwasz/logging-log4j2/pull/566 [3] https://lists.apache.org/list?annou...@apache.org
