btashton commented on a change in pull request #1677: URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480274417
########## 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 said a range _from the HEAD_. I didn't mean that HEAD ~ N is a range. HEAD~N is the Nth commit behind HEAD. > The current branch's top commit is HEAD. > When you are "checkedout" to master and you do `git rebase -i master`, that means you are trying to rebase from HEAD to HEAD, thus the "noop". No you are on your branch and interactive rebase against master. This will show all your commits in the interactive flow. ``` ~/nuttx/nuttx on oldlinks ❯ git rebase -i master pick e34173ab1e Docs: Update links to old website and wiki pick af5b2d5cf7 nxstyle: Fix existing long line to match code style # Rebase 6c227075e7..af5b2d5cf7 onto 6c227075e7 (2 commands) Successfully rebased and updated refs/heads/oldlinks. ``` ---------------------------------------------------------------- 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: [email protected]
