WORK IN PROGRESS

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.

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.
Commiters can ask for others to review or approve. But at the end of the day they are the ones who approve and merge.

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.

This document can be declared a success if newbies and veteran NuttX developers alike find it valuable as both a how-to and a reference. We hope you'll find it easy to read and that it eliminates the need to hunt, memorize, or guess about parts of the workflow.

Enthusiastic Contributors Welcome!

NuttX is a free open-source project. If you'd like to participate, whether it's to enhance documentation (even this workflow document) or dive into the nitty gritty of some low-level drivers, please read on!

Also, join the conversation at our dev mailing list by emailing dev-subscribe@nuttx.apache.org. The mailing list is open to the public and archived. You can browse older messages at https://lists.apache.org/list.html?dev@nuttx.apache.org.

Why Contribute to NuttX?

Have you fixed a bug or implemented a new feature in your copy of NuttX? If so, contributing your improvements "upstream," which means getting them included in the official NuttX code, may be in your best interest because it means that you won't have to re-fix, re-implement, or port your changes over when we release a newer version of NuttX. It also increases the likelihood of your code getting more exposure and testing, and with that, the possibility of other people contributing additional improvements to your code, which will benefit you "for free."

Who Are The Players?

Contributor: Anyone who wants to participate in NuttX by contributing improvements.
Committer: A person who can commit improvements directly to the codebase.
PMC: Project Management Committee. (Currently, NuttX is a Podling of the Apache Incubator, so currently this is called the PPMC.)
Upstream: In this document, "upstream" refers to the NuttX project.
Downstream: In this document, "downstream" means anyone who packages, customizes, and/or uses NuttX in their own projects.

Where is The Code?

Sources of NuttX Code

NuttX source code is available in two forms:

As a clone or fork from a NuttX GIT repository, or
As a versioned release in the form of a GZIP'ed tarball

The versioned release tarballs contain no SCM information. They are intended for use with whatever SCM you select in your custom environment.

The code on which versioned releases are based is also available within the NuttX GIT repository clones or forks. Historical releases are identified with tags. For example, the tag nuttx-8.2 identifies the nuttx-8.2 release. A versioned branch could be created with the git command:

git checkout -b <branch-name> nuttx-8.2

REVISIT: Are there any differences between the tagged release in GIT and the contents of a release tarball? (1) It does not include a .version file, and (2) it does have the .git directory and .gitinfo files.

REVISIT: We do not yet know the form of releases for future Apache releases. These will most likely already be on a branch. (Note: The release process should be discussed in a different section, or even a completely separate document.)

NuttX GIT Repositories

The Apache NuttX project uses Git SCM as its version control system.

There are two primary repositories:

nuttx - The real time operating system itself.
apps - Optional applications for the operating system. You can use this repository or make your own custom one.

The main "Single Source of Truth" repositories are hosted by the ASF:

These are synchronized with repositories hosted at GitHub:

The repositories are mirrored at these additional read-only locations:

BitBucket:
- https://bitbucket.org/nuttx/nuttx/
- https://bitbucket.org/nuttx/apps/

Released Code Tarballs

REVISIT: We do not know the form or location of future Apache NuttX releases.

REVISIT: This "Overview" section makes no mention of the buildroot, tools, and uclibc repositories. We do not yet know how/where those will be hosted.

Creating and Submitting Improvements

All contributors, whether seasoned NuttX committers or new contributors, follow the same steps to submit a proposed change. These steps are outlined here. Further details are given in the remainder of this document.

All Contributors:

Optional: Before you begin work, discuss your proposed change on the dev@nuttx.apache.org mailing list. Someone else may already be working on a similar change and perhaps you could collaborate and split the effort. Also, a discussion could help you find out whether your changes are likely to be accepted, and input from other community members might provide some valuable insights.
Review the section "Criteria For Acceptance" in this document.
Obtain a copy of the source code, if you don't already have it. See the section Sources of NuttX Code. Working with a GIT clone may provide the path of least resistance, but you can also work from the latest versioned release tarball.
Develop your changes. Feel free to communicate with the dev@nuttx.apache.org mailing list as often as you need to for guidance.
Submit your changes. This can be achieved by one of several methods, including by GitHub Pull Request (PR) or emailing a textual GIT Pull Request or patch. See the section "How To Submit Changes For Review" in this document for details.

Community/Committer Review:

At this point, the community, especially committers, should review your proposed changes to ensure that the project's criteria are met. These are spelled out in the section "Criteria For Acceptance" in this document.
If any issues are found, you may be asked to correct them and re-submit your changes. Don't be discouraged if this happens; it's a normal part of the open source process. Committers may opt to go ahead and correct minor issues (such as coding style, etc.) instead of sending them back to you.
Once the review has taken place and the project's criteria are met, your changes are ready to be committed to the official repository.

Notes:

No one is obligated to review a change. Generally, committers will review changes that interest them or affect areas they care about. Fortunately, the NuttX community is friendly and has a large following, so chances are pretty good that your changes will be reviewed. (You did discuss your ideas on the mailing list before investing a lot of time, right?)
Only committers are able to commit changes to the NuttX GIT repositories, but all members of the community are encouraged to participate in reviews and discussions. Committers are encouraged to weigh input from the larger community. If you are not (yet) a committer, being actively involved in the project and demonstrating good will and good judgment, can go a long way toward becoming a committer!

How To Submit Changes For Review

We wish to be as accommodating as possible to our users and contributors. As such, we provide several ways for you to

How you submit a release will depend upon what kind of local environment that you have created to manage your NuttX-based development:

If you are using a versioned NuttX release with no SCM information, you will probably need to send patches.
If you are using a clone or fork of the GIT repositories, then you might want to send Pull Requests (PRs) to submit changes, but
If you are using a versioned release branch in the GIT repositories, then you will have to do things a little differently.

By GitHub Pull Request (PR)

By Emailing a Patch

By Emailing a Textual GIT Pull Request

Criteria For Acceptance

This section defines what sorts of things committers will examine and verify before allowing changes into NuttX.

This is documented here for three reasons:

To make it easier for NuttX contributors to get their changes accepted.
As a checklist of things for NuttX committers to look for when reviewing a potential change.
As a specification of checks that can be automated over time, eventually saving everyone a lot of work!

First, there are the universal requirements that apply to all parts of NuttX:

INVIOLABLES, the overarching principles of this project
Coding standard: nx-style
Clean architecture
POSIX compliance
Successful build

All new files contributed to the project must begin with an Apache Source File License Header: https://www.apache.org/legal/src-headers.html

In addition to the universal requirements, various parts of the NuttX system have their own specific needs:

The build system
Tools
Architectural support
Board support
Scheduler
System calls
Libraries

REVISIT: This section is incomplete! Please leave the bulletpoints above as-is, and develop the text in new subheadings below.