Ouss4 commented on a change in pull request #1677: URL: https://github.com/apache/incubator-nuttx/pull/1677#discussion_r480284330
########## 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: > There shouldn't be any work on master on NuttX (much less any rebasing) Yes, "master" was used just as example. Ok, now I got you. You are actually doing both the rebasing on top of master and any other interactive rebase operation you want to do at the same time. I personally don't use both at the same time. I squash or drop commits on the branch and not rebase ontop of master until I'm done. (and no, I don't use rev-list, there are enough bash/zsh plugins that give the number of commits.) But I'll concide if you guys find it better this way. ---------------------------------------------------------------- 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]
