On Fri, May 28, 2021, 7:54 AM Nathan Hartman <hartman.nat...@gmail.com> wrote:
> On Fri, May 28, 2021 at 9:12 AM Sebastien Lorquet <sebast...@lorquet.fr> > wrote: > > > I'm not talking of renaming code symbols like up_anything to > > arm_anything, which makes sense and can be noticed quite easily at link > > stage. > > > > I'm talking about renaming a shell/make variable from EXTRADEFINES to > > EXTRAFLAGS. This is hidden, and the build system has no way to complain > > about anything missing. > > > > Of course, this has no impact on any built-in board, because the change > > was made locally. so CI cannot detect this. > > > > But this breaks ALL the custom boards people actually use for real > > projects. > > > > And the relevant documentation is hidden at the bottom of some obsolete > > (nuttx 9) release notes, in a "concerns" section. > > > > This doc is critical from anyone porting a custom board from pre-9 nuttx > > to current one. > > > > I cant believe I'm the only one in this case... > > > > Sebastien > > > > Yes, it's documented way near the bottom of the very long ReleaseNotes file > and is hard to find. > > Several things we could do to improve: > > 1. When we make a change like this, detect the obsolete define in the build > system and give some kind of warning? > 2. Split up the ReleaseNotes file? As it is now, it reads a bit more like a > ChangeLog rather than ReleaseNotes. In the past we talked about a > Documentation/ReleaseNotes directory that could hold a separate > ReleaseNotes for each major version? > They are broken out per release and linked on the download page. > 3. Make a ReleaseNotes section of the website that will render those > ReleaseNotes files and offer an easy to use index, so it's easier to find > this information. The newer ones are Markdown but not rendered as such when > opened in any text editor or browser because of all the preexisting > non-markdown content. > Already done http://nuttx.apache.org/releases/10.0.0/#compatibility-concerns > 4. Add a troubleshooting (or FAQ) section to the website and add this > EXTRAFLAGS case to it, i.e., list the symptom and give this as a potential > cause to check for. > > 5. We use semantic versioning, but it would be worthwhile to check if the > major version number was bumped in the first release that contained this > change. If not, that might have been a mistake. > This was part of the reason for making the major version number jump for this release. We already do so much to try and not break things. If you are going to jump 3 major release versions that span __6 years__ you have to expect to run into something and should read at least the compatibility comments for the major releases. I'm all for changing the release notes to be easier to use and they take a huge amount of time to compile. But it is disingenuous to say that nothing was done. --Brennan
