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? 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. 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. Any other thoughts? Nathan
