WORK IN PROGRESS

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:

...

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

Versioned GIT Branches

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:

...

REVISIT: We do not yet know the form of releases for future Apache releases.  These will most likely already be on a branch and will include the .version file on that 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.

...

• https://github.com/apache/incubator-nuttx/
• https://github.com/apache/incubator-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.

The Workflow

All contributors, whether seasoned NuttX committers or new contributors, follow the same steps to submit a proposed change.

...

Now we will go into detail on each step:

Obtain a Copy of the Source Code

You can choose to make a GIT clone and develop your changes against it. Alternatively, you can obtain a versioned release tarball. (You can optionally import the contents of a release into whichever SCM / VCS software you prefer.)

...

• If you are using a versioned NuttX release, which comes 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.

Obtaining and Setting Up a Versioned Release

REVISIT: How to obtain the tarball; how to un-tar it; what steps (if any) should be taken before beginning work on customizations.

Obtaining and Setting Up a GIT Clone or Fork

REVISIT: Give detailed instructions on how to clone the repositories, and what steps to take before beginning work on customizations. (I recommend immediately creating a branch with 'git checkout -b <branch name>' .) What is the purpose of this branch?  Aren't these "Obtaining" paragraphs redundant?  Isn't that addressed above?  Some kind of reorganization is needed, either eliminating some redundant paragraphs or moving information from above to here.

...

Committers Only.  It is especially important that NuttX committers use forks rather than clones for code modification.  Committers have write privileges directly into NuttX repositories and so also bear the responsibility of being especially careful not to accidentally make unauthorized modifications to the repositories. If committers use GIT clones of the NuttX repositories, then there is the constant risk of an error that inadvertently modifies the upstream repositories.  When the committer functions as a contributor, this responsibility is best supported by using a safe fork rather than an uncontrolled clone.

Develop Your Changes

This document describes the workflow of how to get changes upstreamed into the official NuttX repositories. The technical details of how to develop changes are beyond the scope of this document. However, we will take this opportunity to remind you to:

• Be mindful of the Criteria For Acceptance, and
• Feel free to communicate with the dev@nuttx.apache.org mailing list as often as you need to for guidance.

Submit Your Changes For Review

At this point, you have fixed a bug, implemented a new feature, or made some other improvement to your local copy of NuttX. To get your changes into the official NuttX repositories, it helps tremendously if you can package them into a format that conveys the changes accurately.

...

• If you are using a versioned NuttX release, which comes with no SCM information, you will probably need to send patches. See If Working From a Versioned NuttX Release below.
• If you are using a clone or fork of the GIT repositories, then you have several options, including Pull Requests (PRs). See If Working From a Clone or Fork of the GIT Repositories below.
• If you are using a versioned release branch in the GIT repositories, then you will have to do things a little differently. See If Working Using a Versioned Release Branch below.

If Working From a Versioned NuttX Release

REVISIT: Describe in detail, how to make the relevant patch(es) when working with a versioned NuttX release tarball with no SCM information.

If Working From a Clone or Fork of the GIT Repositories

When working from a clone or fork of the GIT repositories, you can submit your changes by one of the following methods:

• Generating a Patch from a Clone
• Generating a GitHub Pull-Request from a Fork
• Generating a Textual GIT Pull-Request from a Clone

Before Submitting Your Changes

You need to ensure that the changes you are going to submit do not conflict with the repository and are ready for a clean merge.
This is achieved by rebasing your commits on top of the current upstream branch.

git fetch upstream # First get the latest changes.
git rebase upstream/<branch> # Rebase on top of upstream's branch, could be "master".

... # Fix any conflicts then run git rebase --continue

git push --force-with-lease origin <branch> # Push your changes to your feature branch.
											# A force push is necessary as the history just changed.

Generating a Patch from a Clone

When you are done developing and you are satisfied with your work, you can create a patch using this GIT command:

...

git checkout master         # Switch to master branch
git branch -D <branch_name> # Since the branch has commits that weren't merged,
							# GIT will complain if you try to delete the branch with -d
							# Thus, force it with -D

git pull origin master      # Fetch the latest changes from remote 
                            # and merge them to your local repository.

Generating a GitHub Pull-Request from a Fork

If you are working on a fork, you have the option of creating a Pull-Request (PR) instead.  To create a pull request on a fork, do the following steps (from https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork):

...

Often, a fork will diverge too much from the upstream repository to keep in synchronization properly.  In this case, feel free to create a new private fork, removing the old forked repository first, of course.
It is a common practice to delete a fork after the pull-request has been closed.  GitHub even supports a special shortcut to delete your fork.  After the your PR has been closed, go to the https://github.com/apache/incubator-nuttx/pull/NN page (where NN is the PR number that was assigned to your pull request).  You will see this message on that page:

Pull request closed

If you wish, you can delete this fork of apache/incubator-nuttx.

...

Multiple Branches.  As a general rule it is important not to mix functionally unrelated code into the same pull-request.  Rather, you should consider using multiple branches.  If the current branch is tied up waiting for a PR to be closed and you want to submit an unrelated PR, just create a second branch for the second PR.  When the PR has been merged, you will be provided an option at https://github.com/apache/incubator-nuttx/pull/NN to delete the branch, instead of deleting the whole fork.

Generating a Textual GIT Pull-Request from a Clone

A textual GIT pull-request is similar to a GIT patch, except that it provides additional context that makes it easier to integrate the change with the upstream repository.

REVISIT: Describe how to make a textual GIT pull request (git request-pull) and send to dev@nuttx.apache.org.

If Working Using a Versioned Release Branch

REVISIT: Describe what must be done differently from the above

Community/Committer Review

Criteria For Acceptance

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

...

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

Reference For Committers

This section is a guide and reference for committers regarding how to carry out all the steps to process a proposed change from start to finish.

...

Even veteran NuttX developers and committers are encouraged to read this section and refer back to it, to make their work easier and also to avoid mistakes that might mess up the upstream repositories.

How to Review Changes

Changes should be reviewed to ensure they meet the Criteria For Acceptance described above.

...

REVISIT: What steps should a reviewer actually take? (I.e., should they bring the change to their local computer and try to build a configuration that includes the change?)

How to Process Changes

Committers who use GitHub can benefit from various conveniences and collaboration tools that GitHub offers as part of the platform.

However, we recognize that some committers cannot or will not use GitHub for various reasons. Therefore, we support both possibilities: GitHub and Plain GIT (Non-GitHub).

GitHub

This section explains to committers how to process changes using GitHub.

GitHub Pull Request (PR)

REVISIT: How to process changes that arrive via GitHub Pull Request.

Emailed Textual Pull Request

REVISIT: How to convert these to a GitHub Pull Request (and then proceed from above).

Emailed Textual Patch

REVISIT: How to convert these to a GitHub Pull Request (and then proceed from above).

Plain GIT (Non-GitHub)

This section explains to committers how to process changes using plain GIT (without GitHub).

GitHub Pull Request (PR)

REVISIT: Is there a way for someone who cannot access GitHub to get access to a change?

Emailed Textual Pull Request

REVISIT: How to process these SAFELY using plain GIT (without messing up the upstream repositories).

Emailed Textual Patch

REVISIT: How to process these SAFELY using plain GIT (without messing up the upstream repositories).

...