That makes sense. I always interpreted that as telling possible contributors that they can submit PRs as simple as typo fixes. I agree that the website and MD file should be the same. Maybe a hyperlink is easiest.
Matteo On Thu, Nov 6, 2025, 4:08 PM Tomek CEDRO <[email protected]> wrote: > 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 >
