...
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."
...
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. These steps are outlined here. Further details are given in the remainder of this document
First, we will outline the basic steps. Afterwards, we will go into detail on each step.
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
...
- .
- Develop your changes.
- Submit your changes.
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."
- 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!
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.)
Keep in mind that how you submit changes will depend upon what kind of local environment you have created to manage your NuttX-based development:
- 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
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>' .)
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
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.
As stated earlier, how you submit changes will depend upon what kind of local environment you have created to manage your NuttX-based development:
- 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.
These are described in detail in the following sections:
If Working From a Versioned NuttX Release
REVISIT: Describe in detail, how to make the relevant patch(es).
If Working From a Clone or Fork of the GIT Repositories
REVISIT: By GitHub Pull Request(PR) - Describe how to push from your local git clone to your GitHub Fork and how to open the PR.
REVISIT: By emailing a patch: Describe how to make the relevant patch(es) (git format-patch) and send them to dev@nuttx.apache.org.
REVISIT: By emailing a textual GIT pull request: Describe how to make the relevant file (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.
...