On Thu, Jun 10, 2021 at 3:50 AM Sebastien Lorquet <sebast...@lorquet.fr> wrote: > With that in mind, I am very worried of a supplemental dispersion of > useful documentation. > > At what release/commit does the build system becomes cmake? before that, > please refer to the make build system documentation. chances are that > this doc quickly becomes 404, leaving all users of all versions in the > dark. for commits after that, please refer to this other documentation > on some personal blog, but only for release a.b.c later than this date.
(snip) > So please. Keep NuttX interfaces STABLE for users that need it. It's not > a beta project anymore, it's "mature" as you advertise it, which means > it has some real industrial users that matter more than abstract > technical beauty. EXTRADEFINES now also need to include flags. hah, not > cool. I should rename that to EXTRAFLAGS, thats more cute. But how many > users will suffer from this apparently benign change? These questions > NEED to be asked by developers and contributors and reviewers. We screwed up. I was in the CWIKI just a few moments ago, to create the skeleton for what will be our next ReleaseNotes, and I found out something unfortunate: In the CWIKI copy of the 9.1 ReleaseNotes [1], the EXTRADEFINES -> EXTRAFLAGS change is documented. BUT... In the repo ReleaseNotes file [2], that section is COMPLETELY MISSING! It is also missing on the website [3]. In fact, all the compatibility docs are missing from both places, such as Rename WINTOOL to CONFIG_CYGWIN_WINTOOL, etc. First, I am going to send a PR to fix the ReleaseNotes in the repo. Second, we need a new Documentation page, "Migrating From Older NuttX." In this documentation, every compatibility change should be documented, going from the present to at least as far back as NuttX 7.31. We can get all of these from the ReleaseNotes, but they should be consolidated somewhere, so that someone like Sebastien who wants to upgrade from version X to version Y can just go step by step and make the necessary changes. [1] https://cwiki.apache.org/confluence/display/NUTTX/NuttX+9.1#NuttX9.1-CompatibilityConcerns [2] https://github.com/apache/incubator-nuttx/blob/master/ReleaseNotes [3] http://nuttx.apache.org/releases/9.1.0/ Nathan
