CINXE.COM

<!DOCTYPE html> <html lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Getting Started — OpenDev Manual documentation</title> <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" /> <link rel="stylesheet" type="text/css" href="_static/basic.css?v=c058f7c8" /> <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=27fed22d" /> <script src="_static/documentation_options.js?v=5929fcd5"></script> <script src="_static/doctools.js?v=9a2dae69"></script> <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="Developer’s Guide" href="developers.html" /> <link rel="prev" title="OpenDev Manual" href="index.html" /> <link rel="stylesheet" href="_static/custom.css" type="text/css" /> </head><body> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <section id="getting-started"> <span id="id1"></span><h1>Getting Started<a class="headerlink" href="#getting-started" title="Link to this heading">¶</a></h1> <section id="the-opendev-workflow"> <h2>The OpenDev Workflow<a class="headerlink" href="#the-opendev-workflow" title="Link to this heading">¶</a></h2> <p>The OpenDev workflow is centered around Gerrit, which uses the concept of <strong>changes</strong> rather than Pull Requests. To propose a change to a git repository, you start by cloning the repository you’re interested in, then create a branch to work in. You curate a commit on that branch, then propose it to Gerrit using the <strong>git-review</strong> tool:</p> <a class="reference internal image-reference" href="_images/code_review.png"><img alt="_images/code_review.png" src="_images/code_review.png" style="width: 700px;" /> </a> <p>At that point, the proposed change is picked up by our Continuous Integration tool, Zuul, which runs <strong>check tests</strong> on it. The change is available for review by human reviewers. Those automated and human checks may result in you having to amend the proposed commit, then propose it again with git-review. Once the change is approved by both Zuul and the human reviewers, Zuul picks it up again and runs <strong>gate tests</strong> on it before finally merging it.</p> </section> <section id="setting-up-your-gerrit-account"> <h2>Setting up your Gerrit account<a class="headerlink" href="#setting-up-your-gerrit-account" title="Link to this heading">¶</a></h2> <section id="get-a-single-sign-on-openid"> <h3>Get a single sign-on OpenID<a class="headerlink" href="#get-a-single-sign-on-openid" title="Link to this heading">¶</a></h3> <p>Gerrit is currently using <em>Ubuntu One</em> as a SSO provider. You’ll therefore need a <a class="reference external" href="https://login.ubuntu.com/+login">Ubuntu One account</a> to use it. This account will also allow you to use <a class="reference external" href="https://launchpad.net">Launchpad</a>, which some projects on OpenDev use as a bug tracker.</p> </section> <section id="select-a-gerrit-username-and-upload-your-ssh-key"> <h3>Select a Gerrit username and upload your SSH key<a class="headerlink" href="#select-a-gerrit-username-and-upload-your-ssh-key" title="Link to this heading">¶</a></h3> <p>Visit <a class="reference external" href="https://review.opendev.org/">https://review.opendev.org/</a> and click the <code class="docutils literal notranslate"><span class="pre">Sign</span> <span class="pre">In</span></code> link at the top-right corner of the page. Log in with your Ubuntu One OpenID.</p> <p>The first time you sign into OpenDev’s Gerrit site, you will be prompted to “Select a unique username:”. You can enter your Ubuntu One username here, or something else if you want. Type carefully, as once set it cannot be changed.</p> <p>At that point you can already review proposed changes. To propose you own changes, you need to first upload your SSH key to Gerrit. This is done by visiting the <a class="reference external" href="https://review.opendev.org/#/settings/ssh-keys">SSH Public Keys section of your Gerrit settings</a>.</p> </section> <section id="configure-your-local-git-environment"> <h3>Configure your local git environment<a class="headerlink" href="#configure-your-local-git-environment" title="Link to this heading">¶</a></h3> <p>Ensure that you have run these steps to let git know about your email address:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">user</span><span class="o">.</span><span class="n">name</span> <span class="s2">"Firstname Lastname"</span> <span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">user</span><span class="o">.</span><span class="n">email</span> <span class="s2">"your_email@youremail.com"</span> </pre></div> </div> <p>To check your git configuration:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="nb">list</span> </pre></div> </div> <p>You’ll want to make sure that the <code class="docutils literal notranslate"><span class="pre">user.email</span></code> you specify matches at least one you’ve provided to Gerrit. By default this is taken from your OpenID login the first time you authenticate, but you can also change it or add more addresses through the <a class="reference external" href="https://review.opendev.org/#/settings/contact">Contact Information</a> page at any point in the future.</p> </section> <section id="install-the-git-review-utility"> <h3>Install the git-review utility<a class="headerlink" href="#install-the-git-review-utility" title="Link to this heading">¶</a></h3> <p><code class="docutils literal notranslate"><span class="pre">git-review</span></code> is a git subcommand tool that handles all the details of working with Gerrit. You can learn more about git-review by reading its <a class="reference external" href="https://docs.openstack.org/infra/git-review/">documentation</a>.</p> <p>The git-review package is available on all major Linux distributions, so you can use your local package management tooling (apt-get, dnf, yum, zypper, pacman…) to install it directly. For example, on Debian/Ubuntu:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">apt</span><span class="o">-</span><span class="n">get</span> <span class="n">install</span> <span class="n">git</span><span class="o">-</span><span class="n">review</span> </pre></div> </div> <p>On Mac OS X, or most other Unix-like systems, you may install it with <a class="reference external" href="https://pip.readthedocs.org/en/latest/installing.html">pip</a>:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="n">git</span><span class="o">-</span><span class="n">review</span> </pre></div> </div> <p>Git-review assumes that your Gerrit username is the same as the current running user on your operating system. If you are using different usernames and would like to avoid getting prompted, you should configure git to use your Gerrit username, as follows:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">config</span> <span class="o">--</span><span class="k">global</span> <span class="n">gitreview</span><span class="o">.</span><span class="n">username</span> <span class="n">yourgerritusername</span> </pre></div> </div> </section> </section> <section id="proposing-a-change"> <h2>Proposing a change<a class="headerlink" href="#proposing-a-change" title="Link to this heading">¶</a></h2> <section id="clone-and-prepare-the-git-repository"> <h3>Clone and prepare the git repository<a class="headerlink" href="#clone-and-prepare-the-git-repository" title="Link to this heading">¶</a></h3> <p>Clone a repository in the usual way, for example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">opendev</span><span class="o">.</span><span class="n">org</span><span class="o">/<</span><span class="n">namespace</span><span class="o">>/<</span><span class="n">projectname</span><span class="o">></span> <span class="n">cd</span> <span class="o"><</span><span class="n">projectname</span><span class="o">></span> </pre></div> </div> <p>Then ask git-review to configure your repository to know about Gerrit:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">review</span> <span class="o">-</span><span class="n">s</span> </pre></div> </div> <p>Feel free to check any unknown host key fingerprints against the <a class="reference internal" href="developers.html#gerrit-ssh-host-keys"><span class="std std-ref">Gerrit SSH Host Keys</span></a>, and if you get an error about a missing contributor license agreement, see the Developer’s Guide section on the <a class="reference internal" href="developers.html#openstack-individual-contributor-license-agreement"><span class="std std-ref">OpenStack Individual Contributor License Agreement</span></a>.</p> </section> <section id="create-a-change-in-a-topic-branch"> <h3>Create a change in a topic branch<a class="headerlink" href="#create-a-change-in-a-topic-branch" title="Link to this heading">¶</a></h3> <p>Create a <a class="reference external" href="https://git-scm.com/book/en/Git-Branching-Branching-Workflows#_topic_branch">topic branch</a> to hold your work and switch to it:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">TOPIC</span><span class="o">-</span><span class="n">BRANCH</span> </pre></div> </div> <p>Then modify files, and create a git commit as usual, for example using:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">a</span> </pre></div> </div> </section> <section id="submit-a-change-for-review"> <h3>Submit a Change for Review<a class="headerlink" href="#submit-a-change-for-review" title="Link to this heading">¶</a></h3> <p>Now that your commit is ready, all you need to do is to send it to Gerrit for code review:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">review</span> </pre></div> </div> </section> <section id="updating-a-change"> <h3>Updating a Change<a class="headerlink" href="#updating-a-change" title="Link to this heading">¶</a></h3> <p>If the code review process suggests additional changes, make and amend the changes to the existing commit. Leave the existing Change-Id: footer in the commit message as-is, so that Gerrit knows this is an updated patchset for an existing change:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">a</span> <span class="o">--</span><span class="n">amend</span> <span class="n">git</span> <span class="n">review</span> </pre></div> </div> </section> </section> <section id="next-steps"> <h2>Next steps<a class="headerlink" href="#next-steps" title="Link to this heading">¶</a></h2> <p>We have a tutorial: <a class="reference internal" href="sandbox.html#sandbox"><span class="std std-ref">Learn the Gerrit Workflow in the Sandbox</span></a>. If this is your first time contributing to a project hosted by OpenDev, we strongly suggest you follow this tutorial.</p> <p>You’ll find a lot more details about how to use Gerrit and Zuul in our <a class="reference internal" href="developers.html#developer-manual"><span class="std std-ref">Developer’s Guide</span></a>.</p> </section> </section> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="Main"> <div class="sphinxsidebarwrapper"> <p class="logo"> <a href="index.html"> <img class="logo" src="_static/opendev.svg" alt="Logo" /> </a> </p> <search id="searchbox" style="display: none" role="search"> <div class="searchformwrapper"> <form class="search" action="search.html" method="get"> <input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false" placeholder="Search"/> <input type="submit" value="Go" /> </form> </div> </search> <script>document.getElementById('searchbox').style.display = "block"</script><h3>Navigation</h3> <ul class="current"> <li class="toctree-l1 current"><a class="current reference internal" href="#">Getting Started</a><ul> <li class="toctree-l2"><a class="reference internal" href="#the-opendev-workflow">The OpenDev Workflow</a></li> <li class="toctree-l2"><a class="reference internal" href="#setting-up-your-gerrit-account">Setting up your Gerrit account</a></li> <li class="toctree-l2"><a class="reference internal" href="#proposing-a-change">Proposing a change</a></li> <li class="toctree-l2"><a class="reference internal" href="#next-steps">Next steps</a></li> </ul> </li> <li class="toctree-l1"><a class="reference internal" href="developers.html">Developer’s Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="irc.html">IRC Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="core.html">Core Reviewer’s Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="drivers.html">Project Driver’s Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="creators.html">Project Creator’s Guide</a></li> <li class="toctree-l1"><a class="reference internal" href="sandbox.html">Learn the Gerrit Workflow in the Sandbox</a></li> <li class="toctree-l1"><a class="reference internal" href="testing.html">Test Environment</a></li> </ul> <div class="relations"> <h3>Related Topics</h3> <ul> <li><a href="index.html">Documentation overview</a><ul> <li>Previous: <a href="index.html" title="previous chapter">OpenDev Manual</a></li> <li>Next: <a href="developers.html" title="next chapter">Developer’s Guide</a></li> </ul></li> </ul> </div> </div> </div> <div class="clearer"></div> </div> <div class="footer"> ©2024, OpenDev Contributors.. | Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.0.2</a> & <a href="https://alabaster.readthedocs.io">Alabaster 1.0.0</a> | <a href="_sources/gettingstarted.rst.txt" rel="nofollow">Page source</a> </div> </body> </html>