I have a preference for maintaining a separate CHANGES file because it allows us to keep JIRA focused for a committer/contributor audience while the CHANGES file can describe changes that matter for users. Elasticsearch uses a similar mechanism for release notes to what you are proposing, using GitHub instead of JIRA. It works well, but in my opinion the Lucene/Solr process produces better curated release notes.
On Mon, Nov 30, 2020 at 12:25 AM David Smiley <dsmi...@apache.org> wrote: > Well the commit history remains there as well and was converted from SVN > and may eventually be converted to something else. My point is that it has > been retained. On release boundaries, we could not only distribute > Changes.html (a JIRA export) in the assembly (tar.gz) but we could also > commit it to source control on each release branch, and thus will transfer > along with source control into the future, which is way more convenient > than digging up an old binary. > > ~ David Smiley > Apache Lucene/Solr Search Developer > http://www.linkedin.com/in/davidwsmiley > > > On Sun, Nov 29, 2020 at 5:55 AM Dawid Weiss <dawid.we...@gmail.com> wrote: > >> Changes in the repository stay there forever (think >> cvs/svn/git/whatever comes next...). External tools change all the >> time. This is the benefit I see. >> >> Dawid >> >> On Sun, Nov 29, 2020 at 6:32 AM David Smiley <dsmi...@apache.org> wrote: >> > >> > 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 >> >> --------------------------------------------------------------------- >> To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org >> For additional commands, e-mail: dev-h...@lucene.apache.org >> >> -- Adrien
