[GitHub] [incubator-nuttx] btashton commented on a change in pull request #1677: Add Simulator and Drivers guides, and contributing instructions for new users

[GitBox <gi...@apache.org>]

btashton commented on a change in pull request #1677:
URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r483854655



##########
File path: Documentation/contributing/making-changes.rst
##########
@@ -0,0 +1,256 @@
+.. include:: /substitutions.rst
+.. _making-changes:
+
+Making Changes
+==============
+
+If you want to make changes to NuttX, for your own personal use, or to submit them back to project to improve NuttX,
+that's easy. For the purposes of this guide, you'll need a `GitHub <https://www.github.com>`_ account, since
+the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
+`GitLab <https://about.gitlab.com/>`_ or `BitBucket <https://bitbucket.org>`_, but that's beyond the scope of this
+guide).
+
+Here's how to do it:
+
+#. Set your git user name and email
+
+    .. code-block:: bash
+
+       $ cd nuttx/
+       $ git config --global user.name "Your Name"
+       $ git config --global user.email "yourname@somedomaincom"
+
+#. Sign in to GitHub
+
+   If you don't have a `GitHub <https://www.github.com>`_ account, it's free to
+   sign up.
+   |br|
+   |br|
+
+
+#. Fork the Project
+
+   Visit both these links and hit the Fork button in the upper right of the page:
+
+   * `NuttX <https://github.com/apache/incubator-nuttx/>`_
+   * `NuttX Apps <https://github.com/apache/incubator-nuttx-apps/>`_
+
+
+#. Change the Git Remotes
+
+   The git repositories in your project are currently connected to the official NuttX repositories, but you don't
+   have permission to push software there. But you can push them to your forks, and from there create Pull Requests
+   if you want to send them to the NuttX project.
+
+   First, remove the current remote, ``origin`` (we'll add it back later):
+
+    .. code-block:: bash
+
+       $ cd nuttx/
+       $ # display the remote
+       $ git remote -v
+
+   You should see something like this:
+
+    .. code-block:: bash
+
+       origin	https://github.com/apache/incubator-nuttx.git
+
+   Now, on the GitHub web page for your forked ``incubator-nuttx`` project, copy the clone url – get it by hitting the
+   green ``Clone or Download`` button in the upper right. Then do this:
+
+    .. code-block:: bash
+
+       $ git remote rm origin
+       $ git remote add origin <your forked incubator-nuttx project clone url>
+       $ git remote add upstream https://github.com/apache/incubator-nuttx.git
+
+   Do the same for your forked ``incubator-nuttx-apps`` project:
+
+    .. code-block:: bash
+
+       $ cd ../apps
+       $ git remote rm origin
+       $ git remote add origin <your forked incubator-nuttx-apps project clone url>
+       $ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
+
+
+#. Create a Local Git Branch
+
+   Now you can create local git branches and push them to GitHub:
+
+    .. code-block:: bash
+
+       $ git checkout -b test/my-new-branch
+       $ git push
+
+
+Git Workflow With an Upstream Repository
+----------------------------------------
+
+The main NuttX git repository is called an "upstream" repository - this is because it's the main source of truth, and
+its changes flow downstream to people who've forked that repository, like us.
+
+Working with an upstream repo is a bit more complex, but it's worth it since you can submit fixes and features
+to the main NuttX repos. One of the things you need to do regularly is keep your local repo in sync
+with the upstream. I work with a local branch, make changes, pull new software from the upstream and merge it in,
+maybe doing that several times. Then when everything works, I get my branch ready to do a Pull Request. Here's how:
+
+#. Fetch upstream changes and merge into my local master:
+
+    .. code-block:: bash
+
+       $ git checkout master
+       $ git fetch upstream
+       $ git merge upstream/master
+       $ git push
+
+#. Merge my local master with my local branch:
+
+    .. code-block:: bash
+
+       $ git checkout my-local-branch
+       $ git merge master
+       $ git push

Review comment:
       I would like to drop it because we get people doing the merge where there might have been a change causing a merge commit and have to ask them to rebase.
   
   Rebase is also the system that the CI system uses for a "merge" so it would be best to keep inline with that.




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org