Couldn't help pitching in here and making a humble request. The CHANGES.txt has been of immense help for us for determining the right upgrade version for our production deployments. So CHANGES.txt or no CHANGES.txt, I hope we'll retain a mechanism to clearly be able to track the changes in subsequent versions.
Thanks, Rahul On Mon, Nov 30, 2020 at 9:04 AM David Smiley <[email protected]> wrote: > I get your point on different audiences... sometimes I peer-review us on > dubiously written CHANGES.txt entries to be more user friendly. However, > this attention could and should be given to JIRA issue summaries as well. > We all benefit from that. Also, for Solr in particular, the need for > examining CHANGES / JIRA is reduced because we have a solr-upgrade-notes.adoc > which is editorialized and covers just the important stuff; no minor > matters. We link to this from release announcements. > > ~ David Smiley > Apache Lucene/Solr Search Developer > http://www.linkedin.com/in/davidwsmiley > > > On Mon, Nov 30, 2020 at 3:29 AM Adrien Grand <[email protected]> wrote: > >> 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 <[email protected]> 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 <[email protected]> >>> 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 <[email protected]> >>>> 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: [email protected] >>>> For additional commands, e-mail: [email protected] >>>> >>>> >> >> -- >> Adrien >> >
