+1 - We need more and better documentation!
- We need to keep existing documentation up to date after modifications. I think all reviewers should pay attention to it and have the courage to ask it to the PR author (I know it is kind of uncomfortable to ask for, but we need to do it for the quality of our project). BR, Alan On Thu, Feb 6, 2025 at 12:55 PM Matteo Golin <matteo.go...@gmail.com> wrote: > Hello, > > If I may add to the proposed contributing guideline changes: all changes > affecting behaviour/APIs or adding features should be properly documented, > not just within the PR. NuttX has many features and lots of apps for using > them, but a lot of them are left undocumented outside of inline comments or > PR descriptions. I think if changes are made then corresponding RST > documentation for the website should be made/updated too. This lets us look > for information in one unified place, especially for users who have no > interest in grepping through the source code. > > With this requirement, all of the sensor drivers and apps that currently > have no documentation would have been documented, for instance. This saves > work for the project later since we don't have to go back and re-read the > code to document things. > > Matteo > > On Thu, Feb 6, 2025 at 10:10 AM Alan C. Assis <acas...@gmail.com> wrote: > > > Hi Tomek, > > > > You missed that rule: > > > > * If one person approves a PR and no other reviews or objections after a > > week, the person who approved the PR can assume a "lazy consensus" and go > > ahead and merge. > > > > BR, > > > > Alan > > > > On Thu, Feb 6, 2025 at 12:46 AM Tomek CEDRO <to...@cedro.info> wrote: > > > > > Hello world :-) > > > > > > We have long discussions over the last months NuttX code quality and > > > self-compatibility degradation. I think open discussion in this area > > > as for 2025Q1 can be constructive. Please join the discussion :-) > > > > > > After we have a good understanding and agreement on selected points we > > > should update Contributing Guidelines both for developers and > > > reviewers. > > > > > > * Each PR _must_ adhere to requirements presented in Contributing > > > Guidelines or be auto-rejected, that is present what this change does, > > > why it is necessary, what if fixes and how, what is the impact, how it > > > was tested (build and runtime test logs mandatory!!). > > > * Number of required code reviews should be increased from 2 to 4. > > > This will ensure cross-checks and filter out faulty changes. > > > * Reviews should come from independent organizations. > > > * Single company commit, review, merge is not allowed. > > > * Self commited code merge is not allowed. > > > * Each commit message must adhere to above (i.e. mandatory and > > > self-explanatory topic and body with description, both topic and > > > description are mandatory, may be simple single sentence or bullet > > > points) or it will be auto-rejected. Simple changes require simple > > > description, complex changes more, potentially breaking changes or big > > > changes require solid proof nothing gets broken. > > > * Both PR description _and_ commit messages are important especially > > > in case of problems. If something gets broken we will be able to > > > understand what was the goal of change.. or just by reading the git > > > log to know what changed why and how. Verification logs may be part of > > > PR only as these will be too long for git log. > > > * If change touches Build / Kernel / Architecture it must be presented > > > and discussed on the mailing list with the community first. PR may be > > > created with clear indication it is for discussion and marked as draft > > > not to be "accidentally merged". > > > * If change touches Build / Kernel / Architecture then build and > > > runtime test (i.e. apps/ostest) logs from developer working on a real > > > world hardware are mandatory! > > > * If change touches Build / Kernel / Architecture build and qemu is > > > not enough as it does not catch all problems visible on real world > > > hardware as we saw recently. > > > * We should implement zero trust approach to user provided testing. > > > * It is commit author to provide real world hardware build and runtime > > > logs that change does not break stuff. > > > > > > Also it will be nice to have monthly online meetings just to talk > > > things over and stay connected and synchronized. It should bring > > > community closer together :-) > > > > > > There were also other nice ideas, please join the discussion :-) > > > > > > Tomek > > > > > > -- > > > CeDeROM, SQ7MHZ, http://www.tomek.cedro.info > > > > > >
