Thanks Alan, yes docs should reflect Contributing Guidelines 1:1 maybe a dedicated page for easier maintenance? :-)
On Thu, Nov 6, 2025 at 10:00 PM Alan C. Assis <[email protected]> wrote: > > Yes, I think you and Matteo are right, the CONTRIBUTING.md makes it clean, > but the online Contributing Documentation doesn't: > > https://nuttx.apache.org/docs/latest/contributing/documentation.html > > "Contributions to documentation are appreciated. These can be as simple as > fixing a typo or formatting issues to more involved changes such as > documenting parts of NuttX which are not yet covered or even writing guides > for other users." > > So, is it "appreciated or required" ? :-D > > I think "we have a problem", there is not a single point of truth, we have > information spread all over the places and conflicting. > > After voting, let's make the online Contributing Documentation reflecting > CONTRIBUTING.md and the definitions included here. > > BR, > > Alan > > On Thu, Nov 6, 2025 at 5:47 PM Tomek CEDRO <[email protected]> wrote: > > > Alan we already have Documentation Requirements in the Contributing > > Guidelines [1]. What we are exactly voting for and what is the > > intended voting outcome / action? > > Tomek > > > > 1.8. Documentation requirements. > > > > Changes must come with a documentation update (where applicable). > > > > Documentation is part of the nuttx git repository. If code change is > > part of nuttx-apps repository then separate PR in nuttx repository is > > required. Otherwise documentation should come in the same PR as the > > code update. > > > > It is advised that the code and documentation should be split into two > > separate commits in the same PR. This helps backporting and separates > > possible code and documentation build errors. Squashing code together > > with documentation into a single commit should be avoided, but is > > acceptable. > > > > If change presents new functionality documentation must be provided in > > the same PR along with the code (not in the future). > > > > If change requires existing documentation update it must be contained > > in the same PR along with the code change (not in the future). > > > > Successful documentation build logs (shortcut) are welcome. > > > > This helps us keep documentation in sync with the code. > > > > See: > > > > https://github.com/apache/nuttx/tree/master/Documentation > > https://github.com/apache/nuttx/blob/master/INVIOLABLES.md > > > > [1] > > https://github.com/apache/nuttx/blob/master/CONTRIBUTING.md#18-documentation-requirements > > > > On Thu, Nov 6, 2025 at 8:59 PM Alan C. Assis <[email protected]> wrote: > > > > > > As discussed in [1] we need to improve our Documentation and requesting > > > Documentation from the author of the new added Features seems to be the > > > best approach. > > > > > > So these are the proposals to be voted: > > > > > > - Anyone submitting a new features should write Documentation to it, > > which > > > he/she is the author is knows more about that features than other people > > > and could write better Documentation; > > > > > > - Anyone adding a new function (or a new resource such as ioctl, etc) > > > should include it in the existing Documentation; If there is not > > > Documentation for that Feature/Driver/whatever, then the Reviews should > > > suggest the contributor to submit a basic page (without forcing him to do > > > it) > > > > > > I think these are the key points collected from the previous discussion. > > > > > > BR, > > > > > > Alan > > > > > > 1 - https://lists.apache.org/thread/5dklb9r2k9vpl9jwpromdn0lcv3h0985 > > > > > > > > -- > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > -- CeDeROM, SQ7MHZ, http://www.tomek.cedro.info
