blob: db6ce768d47769519eff7900ab21c9c0e56c152e [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Making Changes Using Git &mdash; NuttX latest documentation</title>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/segment.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/menu.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/semantic-ui-2.4.1/tab.min.css" type="text/css" />
<link rel="stylesheet" href="../_static/sphinx_tabs/tabs.css" type="text/css" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
<link rel="shortcut icon" href="../_static/favicon.ico"/>
<!--[if lt IE 9]>
<script src="../_static/js/html5shiv.min.js"></script>
<![endif]-->
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="C Coding Standard" href="coding_style.html" />
<link rel="prev" title="Development Workflow" href="workflow.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> NuttX
<img src="../_static/NuttX.png" class="logo" alt="Logo"/>
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../latest" selected="selected">latest</option>
<option value="../../10.0.0" >10.0.0</option>
<option value="../../10.0.1" >10.0.1</option>
<option value="../../10.1.0" >10.1.0</option>
<option value="../../10.2.0" >10.2.0</option>
<option value="../../10.3.0" >10.3.0</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<p class="caption"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../components/index.html">OS Components</a></li>
<li class="toctree-l1"><a class="reference internal" href="../applications/index.html">Applications</a></li>
<li class="toctree-l1"><a class="reference internal" href="../boards/index.html">Supported Boards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../releases/index.html">Releases</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Contributing</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="workflow.html">Development Workflow</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">Making Changes Using Git</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#git-workflow-with-an-upstream-repository">Git Workflow With an Upstream Repository</a></li>
<li class="toctree-l3"><a class="reference internal" href="#submitting-your-changes-to-nuttx">Submitting Your Changes to NuttX</a></li>
<li class="toctree-l3"><a class="reference internal" href="#git-resources">Git Resources</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="coding_style.html">C Coding Standard</a></li>
<li class="toctree-l2"><a class="reference internal" href="documentation.html">Documentation</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../glossary.html">Glossary</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home"></a> &raquo;</li>
<li><a href="index.html">Contributing</a> &raquo;</li>
<li>Making Changes Using Git</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/contributing/making-changes.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="making-changes-using-git">
<span id="making-changes"></span><h1>Making Changes Using Git<a class="headerlink" href="#making-changes-using-git" title="Permalink to this headline"></a></h1>
<p>The Apache NuttX project uses the <a class="reference external" href="https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control">Git version control system</a>
to track changes, and the source code is hosted on <a class="reference external" href="https://www.github.com">GitHub</a>.</p>
<p>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 <a class="reference external" href="https://www.github.com">GitHub</a> account, since
the Apache NuttX team uses GitHub. (You could also use git locally, or save your changes to other sites like
<a class="reference external" href="https://about.gitlab.com/">GitLab</a> or <a class="reference external" href="https://bitbucket.org">BitBucket</a>, but that’s beyond the scope of this
guide).</p>
<p>Here’s how to do it:</p>
<ol class="arabic">
<li><p>Set your git user name and email</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> nuttx/
$ git config --global user.name <span class="s2">&quot;Your Name&quot;</span>
$ git config --global user.email <span class="s2">&quot;yourname@somedomaincom&quot;</span>
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Sign in to GitHub</p>
<p>If you don’t have a <a class="reference external" href="https://www.github.com">GitHub</a> account, it’s free to
sign up.</p>
</li>
<li><p>Fork the Projects</p>
<p>Visit both these links and hit the Fork button in the upper right of the page:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/apache/incubator-nuttx/">NuttX</a></p></li>
<li><p><a class="reference external" href="https://github.com/apache/incubator-nuttx-apps/">NuttX Apps</a></p></li>
</ul>
</li>
<li><p>Clone the Repositories</p>
<p>On the GitHub web page for your forked <code class="docutils literal notranslate"><span class="pre">incubator-nuttx</span></code> project, copy the clone url – get it by hitting the
green <code class="docutils literal notranslate"><span class="pre">Clone</span> <span class="pre">or</span> <span class="pre">Download</span></code> button in the upper right. Then do this:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone &lt;your forked incubator-nuttx project clone url&gt;
$ git remote add upstream https://github.com/apache/incubator-nuttx.git
</pre></div>
</div>
</div></blockquote>
<p>Do the same for your forked <code class="docutils literal notranslate"><span class="pre">incubator-nuttx-apps</span></code> project:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ <span class="nb">cd</span> ../apps
$ git clone &lt;your forked incubator-nuttx-apps project clone url&gt;
$ git remote add upstream https://github.com/apache/incubator-nuttx-apps.git
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Create a Local Git Branch</p>
<p>Now you can create local git branches and push them to GitHub:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git checkout -b test/my-new-branch
$ git push
</pre></div>
</div>
</div></blockquote>
</li>
</ol>
<div class="section" id="git-workflow-with-an-upstream-repository">
<h2>Git Workflow With an Upstream Repository<a class="headerlink" href="#git-workflow-with-an-upstream-repository" title="Permalink to this headline"></a></h2>
<p>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.</p>
<p>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:</p>
<ol class="arabic">
<li><p>Fetch upstream changes and merge into my local master:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git checkout master
$ git fetch upstream
$ git merge upstream/master
$ git push
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Merge my local master with my local branch:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git checkout my-local-branch
$ git merge master
$ git push
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Make changes and push them to my fork</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ vim my-file.c
$ git add my-file.c
$ git commit my-file.c
$ git push
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Repeat 1-3 as necessary</p></li>
<li><p>Run the <code class="docutils literal notranslate"><span class="pre">tools/checkpatch.sh</span></code> script on your files</p>
<p>When your code runs, then you’re almost ready to submit it. But first you need to check the code to ensure
that it conforms to the NuttX <a class="reference internal" href="coding_style.html#c-coding-standard"><span class="std std-ref">C Coding Standard</span></a>.
The <code class="docutils literal notranslate"><span class="pre">tools/checkpatch.sh</span></code> script will do that. Here’s the usage info:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ./tools/checkpatch.sh -h
USAGE: ./tools/checkpatch.sh <span class="o">[</span>options<span class="o">]</span> <span class="o">[</span>list<span class="p">|</span>-<span class="o">]</span>
Options:
-h
-c spell check with codespell<span class="o">(</span>install with: pip install codespell
-r range check only <span class="o">(</span>used with -p and -g<span class="o">)</span>
-p &lt;patch list&gt; <span class="o">(</span>default<span class="o">)</span>
-g &lt;commit list&gt;
-f &lt;file list&gt;
- <span class="nb">read</span> standard input mainly used by git pre-commit hook as below:
git diff --cached <span class="p">|</span> ./tools/checkpatch.sh -
</pre></div>
</div>
</div></blockquote>
<p>Run it against your files and correct all the errors in the code you added, so that
<code class="docutils literal notranslate"><span class="pre">tools/checkpatch.sh</span></code> reports no errors. Then commit the result.
For example:</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ ./tools/checkpatch.sh -f my-file.c
arch/arm/src/sama5/hardware/my-file.c:876:82: warning: Long line found
$ <span class="c1"># fix errors</span>
$ vim my-file.c
$ <span class="c1"># run again</span>
$ ./tools/checkpatch.sh -f my-file.c
</pre></div>
</div>
</div></blockquote>
<p>If you have made a lot of changes, you can also use this bash commandline to see the errors for all the changed C
files in your branch (assumes you are currently on the branch that has the changed files):</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git diff --name-only master <span class="p">|</span> egrep <span class="s2">&quot;\.c|\.h&quot;</span> <span class="p">|</span> xargs <span class="nb">echo</span> <span class="p">|</span> xargs ./tools/checkpatch.sh -f <span class="p">|</span> less
</pre></div>
</div>
</div></blockquote>
<p>Note that there are some bugs in the <code class="docutils literal notranslate"><span class="pre">nxstyle</span></code> program that <code class="docutils literal notranslate"><span class="pre">checkpatch.sh</span></code> uses, so
it may report a few errors that are not actually errors. The committers will help you
find these. (Or view the
<a class="reference external" href="https://github.com/apache/incubator-nuttx/issues?q=is%3Aissue+is%3Aopen+nxstyle">nxstyle Issues</a>.)
<br/>
<br/></p>
</li>
<li><p>Commit the fixed files</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git add my-file.c
$ git commit my-file.c
$ git push
</pre></div>
</div>
</div></blockquote>
</li>
</ol>
</div>
<div class="section" id="submitting-your-changes-to-nuttx">
<h2>Submitting Your Changes to NuttX<a class="headerlink" href="#submitting-your-changes-to-nuttx" title="Permalink to this headline"></a></h2>
<blockquote>
<div><p>Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull
request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits
before your changes are merged into the base branch.</p>
<p>(from GitHub’s <a class="reference external" href="https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests">About pull requests</a> page)</p>
</div></blockquote>
<p>Before you do a Pull Request, the NuttX team will usually want all the changes you made in your branch “squashed” into
a single commit, so that when they review your changes, there’s a clean view of the history. If there are changes
after Pull Request review feedback, they can be separate commits. Here’s the easiest way I found to do that initial
squash before submitting the Pull Request:</p>
<ol class="arabic">
<li><p>Check out my branch</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git checkout my-branch
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Fetch the upstream code</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git fetch upstream
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Rebase onto the upstream code</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git rebase upstream/master
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Push to your remote</p>
<p>This needs to a force push with <code class="docutils literal notranslate"><span class="pre">-f</span></code>.</p>
<blockquote>
<div><div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git push -u my-branch -f
</pre></div>
</div>
</div></blockquote>
</li>
<li><p>Create a GitHub Pull Request</p>
<p>A Pull Request is how you ask your upstream to review and merge your changes.</p>
<p>Here’s <a class="reference external" href="https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request">GitHub’s instructions for creating a Pull Request</a>.</p>
</li>
<li><p>Get Pull Request feedback and implement changes</p>
<p>Get suggestions for improvements from reviewers, make changes, and push them to the branch. Once the reviewers are
happy, they may suggest squashing and merging again to make a single commit. In this case you would repeat steps
1 through 6.</p>
</li>
</ol>
</div>
<div class="section" id="git-resources">
<h2>Git Resources<a class="headerlink" href="#git-resources" title="Permalink to this headline"></a></h2>
<ul class="simple">
<li><p><a class="reference external" href="https://github.github.com/training-kit/downloads/github-git-cheat-sheet.pdf">Git Cheat Sheet (by GitHub)</a></p></li>
<li><p><a class="reference external" href="https://git-scm.com/book/en/v2">Git Book (online)</a></p></li>
<li><p><a class="reference external" href="https://cwiki.apache.org/confluence/display/NUTTX/Code+Contribution+Workflow">NuttX Code Contribution Workflow (draft)</a>
– All the details are here if you need them!</p></li>
</ul>
</div>
</div>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, The Apache Software Foundation
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>