I think we need to keep the release notes, they help people understand why they would want to upgrade. Let's make them succinct, however. I like the list of major parts, maybe we can add "Boards" to "Architecture Support" and add another part for other subsystems like, crypto, graphics, net, file systems, etc.
> I think the Release Notes should be on the website, not bundled with > the release tarballs. Rationale: This will allow us to update the > release notes after the release is made. That would be done, e.g., > when known problems are discovered in a release, or to document any > security issue(s) that the release fixes. I think this is better. We can still add a note in the readme file about the latest release and where to find the full release notes. > It's a very different thing than a Changelog. A Changelog contains > every detail of what changed and in my opinion that's an outdated > concept because interested parties can list the Git log, if they > really want to study every single change. I'd be in favor of dumping the Changelog, maybe delete it now? Greg, do you agree? You spent a lot of time with this. On Sun, Mar 29, 2020 at 5:16 PM Nathan Hartman <hartman.nat...@gmail.com> wrote: > > Earlier, in the thread "The Release"... > > On Sun, Mar 29, 2020 at 11:44 AM Gregory Nutt <spudan...@gmail.com> wrote: > > Do we plan to generate Release Notes? In my experience that is the most > > difficult part of the release (the rest is fun). Abdelatif tells me that > > there are 1051 commits. That is a much lower number that I expecteded, > > lower than most old 2 month cycles, but probably still more than anyone > > really wants to dig into in detail. > > > > We can control this level of effort. Perhaps we just want to list major > > new architectures and boards supported. And any major new OS features? > > That would be a relatively low effort. it would be nice to list the > > major bugs that have been fixed but I don't know of any easy way to get > > that. > > I think we should have Release Notes. > > But NOT in excruciating detail!! > > Release Notes are for people who want to know: > * "What's new in this release?" > * "Why would I want to upgrade?" > * "What changes must I make in my application?" > * etc. > > It's a very different thing than a Changelog. A Changelog contains > every detail of what changed and in my opinion that's an outdated > concept because interested parties can list the Git log, if they > really want to study every single change. > > I think the Release Notes should be on the website, not bundled with > the release tarballs. Rationale: This will allow us to update the > release notes after the release is made. That would be done, e.g., > when known problems are discovered in a release, or to document any > security issue(s) that the release fixes. > > When new releases are made, Release Notes should only be added, never > removed, so that people will be able to access release notes for older > versions at any time. > > The release notes could be structured according to the major parts of > the OS. Something like this: > > (1) What's New In This Release > > (A) Maybe a paragraph or two listing the most major new features/changes. > (B) Highlights of project news since last release. > > (2) Compatibility Concerns > > Point out any major changes that require changes by downstream users. > > (3) Major Changes to Core OS > > (A) New or significantly changed > > (4) Major Changes to Build System > > (A) New or significantly changed > > (5) Architectural Support > > (A) List new architectures > (B) List architectures with significant improvements > (C) List removed architectures > > (6) Driver Support > > (A) List major new drivers > (B) List drivers with significant improvements > (C) List removed drivers > > (7) Security Issues Fixed in this Release > > (8) Known Problems in this Release > > (If any) > > (9) More Information > > (A) Where to find the release > (B) How to clone git repository and list full changelog > (C) How to contact the community > > (10) Call to action: Invitation to get involved in Apache NuttX > community and development! > > Thoughts? > > Cheers, > Nathan
