WORK IN PROGRESS
Table of Contents |
---|
Email Context
Nathan sent this email which is a reasonable outline. So I have it here for a reference to work toward, I will be making some changes where I think are appropriate. At the end of the day this probably should go into a CONTRIBUTING file on GitHub.
No Format |
---|
At this point, much has been written in this and other threads.
Now I recommend that we should have a Confluence page where the information
can be edited to make it:
* Plain English
* Flow well
* Readable
* Coherent
* Specific
* Not assume knowledge
* In one easy to find place
I say "I recommend that we should" instead of just going ahead and creating
that Confluence page because I want to ensure that this happens with
community agreement.
Rationale for creating the document: I don't want or expect anyone to
memorize our workflow, nor to go digging all over the place to piece
together what it is. I want it documented clearly so that veteran
contributors and total newbies alike will be able to understand exactly
what to do. I also want this documented for purpose of on-boarding future
committers and so that committers will know what is expected of them
whenever they commit. And furthermore I want it in a clear document that we
can officially vote on to make it our "blessed" workflow, until such time
as we decide to make changes and vote to update the "blessed" process.
The document should flow in a manner that makes information easy to find. I
suggest to organize it as follows:
1. Overview. This section defines "WHAT" the steps of the workflow are.
This is a simple bulleted or numbered list. No rationale, no git jargon, no
DevOps nonsense, just clear plain English. Where is the code. What basic
steps take place to apply changes to it. Greg literally wrote this list a
few emails ago and it contains 80% of what should be in that list. It needs
minimal improvement.
2. How To Submit Changes For Review. This section defines the "HOW" of the
workflow for ANYONE who wants to get a change into NuttX, whether committer
or not. Committers do not get to bypass this process. This section should
document: How to obtain a copy of the code. What steps to take before
beginning work on a change. Once you've made your change and want to
contribute it, what steps to take to turn it into a PR or patch. How to
submit the PR or patch to us? We should NOT assume knowledge. If a step
requires using git, then give the exact git command followed by an
explanation of every element of that command, so that anyone who knows how
to enter a command in a terminal with zero prior knowledge of git will be
able to understand exactly how to issue that git command and exactly what
it will do. I want to make it straightforward and easy for a HARDWARE
engineer to be able to submit changes.
3. Criteria For Acceptance. This section defines what sorts of things
committers will examine and verify before allowing changes into NuttX.
First, the universal requirements that apply to all parts of NuttX. This
includes INVIOLABLES, coding standard, rules that govern clean
architecture, POSIX compliance, not breaking the build, etc. The word
INVIOLABLES should be a link to that file. After the universal
requirements, there should be requirements by area. Requirements for
boards. Requirements for drivers. Requirements for the scheduler.
Requirements for architectural support. Etc. All of the checks in this
section can be performed manually by a committer for now. This section
should be documented clearly and specifically enough that it can directly
be used as the specification of automated checks to implement in a CI
system.
4. Reference For Committers. This section explains to committers how to
carry out all the steps to process a proposed change from start to finish.
"Start" means a patch or a PR arrived. If a patch, how to convert it into a
PR. "Finish" can mean either applying the change to master, or reject the
change / send it back to the submitter for additional work. And all steps
in between. This section (item #4) is a continuation of item #2. Item #2
explained how anyone submits a proposed change for review. Now we explain
what happens next. Like item #2, we should NOT assume knowledge. If a step
requires using git, then give the exact git command followed by an
explanation of every element of that command. This is not excessive. This
will help on-boarding of new committers as well as help veteran committers
avoid mistakes.
5. Rationale. This section explains the "WHY" behind all of the above. So
that people won't cut an inch off each end of a ham without knowing why.
Cheers,
Nathan |
From My Email (will drop this after I fill in the rest)
...
Submit a PR on GitHub against master if it is approved by one commiter (that did not propose it) it can be merged. The approval is done via the GitHub approval system.
...
A commiter may create a PR on behalf of a patch submitted to the mailing list.
...
Overview
Purpose
The purpose is simple: We'd like to help everyone participate in the future of NuttX by providing clear and open documentation on how to contribute.
...