...

• https://github.com/apache/incubator-nuttx/
• https://github.com/apache/incubator-nuttx-apps/

Cloning or Forking the Repositories

Cloning the Repositories:  These are the steps to clone the source code from repository:

Released Code Tarballs

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

Apache project releases are found at https://projects.apache.org/releases.html or https://archive.apache.org/dist/.  However, podling releases are handled differently.  They are released using the Github release system:

• git clone https://github.com/apache/incubator-nuttx nuttx/releases
• git clone https://github.com/apache/incubator-nuttx-apps apps

These will create copies, clones, of the Apache NuttX repositories on your local computer.

Enter inside "nuttx" directory and, if you like, create a branch where you will work:

• cd nuttx
• git checkout -b mybranch origin/dev

Make your modification and commit them as described later in this document.

Clones of repositories are useful for creating patches that you can send to the Apache project for inclusion.  A better workflow, however, would use pull requests and to use pull requests you will need to use a fork instead of a clone.

Forking the Repositories:  A fork of the repository is a clone of the origin repository that exists in your remote GitHub user area.  The "fork & pull" model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository.  The changes must then be pulled into the source repository by the project maintainer. This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.

The forked repository is mostly static.  It exists in order to allow you to publish work for code review purposes. You don't do active development in your forked repository as would do with a cloned repository.  Unlike the cloned respository, the fork does not exist  on your computer, it exists on GitHub's server in the cloud.  Instead, you would do your development on a clone of the fork of the repository.

To create a fork of your repository, follow these steps (from https://help.github.com/en/github/getting-started-with-github/fork-a-repo):

• Create the fork by visiting the https://github.com/apache/incubator-nuttx/.  In the upper right corner, there is a button labeled Fork.  Follow the instructions and this will create a repository in your personal area at https://github.com/<username>/incubator-nuttx.
• Create a local clone of your fork.  On your local PC execute 'git clone <URL>' to create a clone of your fork on your local PC.  You can find the exact URL for that command by visiting https://github.com/<username>/incubator-nuttx and clicking on the Clone or download button.

It may be useful to define a remote name for the original repository.  You will need this later when you re-synchronize your clone:

• Check the list of remotes that you have already:

git remote -v
origin https://github.com/<username>/incubator-nuttx.git (fetch)
origin https://github.com/<username>/incubator-nuttx.git (push)


• Add the NuttX remote:

...

• /releases

REVISIT: The above releases are not the official NuttX releases.  They do not include the .version file.  I am not sure how those were generated but they are incorrect.

Perhaps I am confused.  Perhaps the releases will be at https://archive.apache.org/dist/incubator/incubating-nuttx/ which does not yet exist.

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.

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.
• 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 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.

Cloning the Repositories:  Clones of repositories are useful for creating patches that you can send to the Apache project for inclusion.
These are the steps to clone the repositories:

• git clone https://github.com/apache/incubator-nuttx

...

• nuttx
• git clone https://github.com/apache/incubator-nuttx

...

• -apps apps

You can work directly on the master branch or you can create a branch with the following commands:

git checkout master # If not already in master.
git checkout -b <branch_name> # Create and switch to the branch.

Forking the Repositories:  A fork of the repository is a clone of the origin repository that exists in your remote GitHub user area.  The "fork & pull" model lets anyone fork an existing repository and push changes to their personal fork without requiring access be granted to the source repository.  The changes must then be pulled into the source repository by the project maintainer. This model reduces the amount of friction for new contributors and is popular with open source projects because it allows people to work independently without upfront coordination.

The forked repository is mostly static.  It exists in order to allow you to publish work for code review purposes. You don't do active development in your forked repository as would do with a cloned repository.  Unlike the cloned repository, the fork does not exist  on your computer, it exists on GitHub's server in the cloud.  Instead, you would do your development on a clone of the fork of the repository.

To create a fork of your repository, follow these steps (from https://help.github.com/en/github/getting-started-with-github/fork-a-repo):

...

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.

Released Code Tarballs

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

Apache project releases are found at https://projects.apache.org/releases.html or https://archive.apache.org/dist/.  However, podling releases are handled differently.  They are released using the Github release system:

• https://github.com/apache/incubator-nuttx/releases
• Create the fork by visiting the
• https://github.com/apache/incubator-nuttx-apps/releases

...

• . 

...

• In the upper right corner, there is a button labeled Fork.  Follow the instructions and this will create a repository in your personal area at https://

...

• github.

...

• com/

...

• <username>/incubator

...

• -nuttx

...

• .
• Create a local clone of your fork.  On your local PC execute git clone <URL> to create a clone of your fork on your local PC.  You can find the exact URL for that command by visiting https://github.com/<username>/incubator-nuttx and clicking on the Clone or download button.

It may be useful to define a remote name for the original repository.  You will need this later when you re-synchronize your clone:

• Check the list of remotes that you have already:

git remote -v

origin https://github.com/<username>/incubator-nuttx.git (fetch)
origin https://github.com/<username>/incubator-nuttx.git (push)


• Add the NuttX remote:

git remote add upstream https://github.com/apache/incubator-nuttx.git
git remote -v

origin https://github.com/<username>/incubator-nuttx.git (fetch)
origin https://github.com/<username>/incubator-nuttx.git (push)
upstream https://github.com/apache/incubator-nuttx.git (fetch)
upstream https://github.com/apache/incubator-nuttx.git (push)

Same as the clone workflow, you can work directly on your fork's master branch or create a new branch.

git checkout master #  If not already in master.
git checkout -b <branch_name> # Create and switch to the branch.
git push -u origin <branch_name> # Push the newly created branch to the fork and set it to track the remote branch.

You can check the branches you have and what remote branches they are tracking with:

git branch -vv

master        <commit_sha>  \[origin/master\] <commit_msg>
<branch_name> <commit_sha>  \[origin/<branch_name>\] <commit_msg>

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

...

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.

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.
• 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 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.

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:

...

Now, you need to re-synch your local clone. It's important to note that committers can perform some minor changes on your behalf, so always pull the latest changes.
If you were working on a branch, just delete the branch and pull master. You can do this with the following GIT commands.

git checkout master # If you are not already in master.

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.

...

REVISIT: Anything better than the cruel reset --hard?

git reset --hard origin/master # Reset back to origin.

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

...