> Hmmm... I believe that the whole point of Release Notes is to point > out things like Compatibility Concerns that our downstream users and > developers will want to know about before they attempt to update and > learn the hard way that their code doesn't build or doesn't run > correctly. But that's just my opinion. Let's see what others think.
I agree that it's important to highlight compatibility concerns and guide downstream users, it just didn't fit in that file. Sorry I wasn't too clear, it was a suggestion and I should have mentioned that anyone could push to the PR and change it if need be. > Perhaps we could consider an alternate solution: Instead of one huge > ReleaseNotes file that will only continue growing without bounds, > perhaps the ReleaseNotes file should document the latest release only, > and all prior release notes could be moved to separate files in a > subdirectory? Each time we make a release, move ReleaseNotes into that > subdirectory (and rename it, e.g., ReleaseNotes-9.1) and create a new > ReleaseNotes file in its place? It has been suggested before to keep only the latest release notes in the top level file. The downside was that we didn't want users to juggle with GIT to retrieve earlier release notes. Having a subdir with the old release notes could actually solve both issues. Another point is the template format. What are your thoughts on using Markdown? Both in the Wiki and in ReleaseNote. Using it in the Wiki will ease copy pasting without being concerned about formatting (Thanks Brennan for fixing the PR!) and in the ReleaseNote we will still have a readable text file but also one that can be auto formatted by any Markdown-aware tool/website. On Tue, Jun 23, 2020 at 4:36 AM Nathan Hartman <hartman.nat...@gmail.com> wrote: > > On Mon, Jun 22, 2020 at 10:13 PM Brennan Ashton <bash...@brennanashton.com> > wrote: > > > On Mon, Jun 22, 2020, 5:38 PM Nathan Hartman <hartman.nat...@gmail.com> > > wrote: > > > > > On Mon, Jun 22, 2020 at 4:46 PM Abdelatif Guettouche > > > <abdelatif.guettou...@gmail.com> wrote: > > > > I created a PR copying the release notes from Confluence to ReleaseNote > > > file. > > > > I did not copy the "Compatibility Concerns" part, that's valuable > > > > information but I don't think it belongs to that file, just because > > > > there is a lot of explanation and code snippets which are not well > > > > suited for the template of that file. > > > > Speaking of which, I believe we should reconsider the ReleaseNote file > > > > and its content. It's hard to navigate a 27K+ file. That's a > > > > discussion for another thread, just put it here as a reminder for > > > > myself. > > > > > > Hmmm... I believe that the whole point of Release Notes is to point > > > out things like Compatibility Concerns that our downstream users and > > > developers will want to know about before they attempt to update and > > > learn the hard way that their code doesn't build or doesn't run > > > correctly. But that's just my opinion. Let's see what others think. > > > > > > > Nathan, > > Do you want to make any of these changes for this release? I would like to > > bring the Release Notes in the to release branch to cut a release in the > > next few hours. > > > > I agree that we should probably have some discussion about release notes > > and documentation going forward. > > > > I think it's best to proceed with the release candidate as-is. > > I agree with Abdelatif that the release notes file is beginning to grow too > large to add so much new information to it, so I think that we should as a > community discuss how to deal with this moving forward. For now, the > information is documented at the wiki. > > Thanks, > Nathan
