After recently proposing per-module CHANGES.md... I think I'd actually rather not have any CHANGES file at all to maintain. I'd rather go to JIRA with a bit better hygiene for metadata like components==contrib/module, and have some convenient links sprinkled about so that it's a convenient click away from each module. This proposal may not be as compelling for Lucene which has no solr-upgrade-notes.adoc file.
Maintaining this CHANGES file (or files) is a pain. Formatting it just-so & conversion to HTML & other scripts manipulating it in dev-tools (e.g. add version), and branch syncing. It's commonly a source of merge conflicts more than any other file. It's an annoying step with GitHub PRs in particular. Why do we bother? Instead, on releases, provide a JIRA link to display all fixed issues grouped by issue type. We could export it to a file for direct inclusion in the distribution. JIRA even has a feature for this -- here's a direct link for 8.7: https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310230&version=12348463 Notice the HTML version at the bottom. It could be dumped into the release binaries. Issue summaries tend to be much shorter than CHANGES.txt bullets but I think that's okay because it's not the only information available for those who want to know more. Remember there is also all the other metadata in JIRA a user can examine, there are commit messages, sometimes PRs, and there's solr-upgrade-notes.adoc which ought to be the starting point for someone interested in a release. It's been argued that contributors should get attribution here but we could maintain a separate contributors file to acknowledge people by name for inclusion with the Solr distribution -- one that has a link to JIRA and GitHub even. ~ David Smiley Apache Lucene/Solr Search Developer http://www.linkedin.com/in/davidwsmiley
