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
