CINXE.COM
Developer’s Guide — OpenDev Manual documentation
<!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>Developer’s Guide — 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="IRC Guide" href="irc.html" /> <link rel="prev" title="Getting Started" href="gettingstarted.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="developer-s-guide"> <span id="developer-manual"></span><h1>Developer’s Guide<a class="headerlink" href="#developer-s-guide" title="Link to this heading">¶</a></h1> <p>The goal of this document is to walk you through the concepts and specifics that should be understood while contributing to projects hosted in the OpenDev infrastructure.</p> <section id="accounts-creation"> <h2>Accounts creation<a class="headerlink" href="#accounts-creation" title="Link to this heading">¶</a></h2> <p>The steps necessary to create a Gerrit account are described in <a class="reference internal" href="gettingstarted.html#getting-started"><span class="std std-ref">Getting Started</span></a>. Only extra recommended steps will be described here.</p> <section id="irc-account"> <h3>IRC Account<a class="headerlink" href="#irc-account" title="Link to this heading">¶</a></h3> <p>While development on OpenDev only requires an account on the OpenDev Gerrit Code Review System, <strong>effective</strong> development in OpenDev hosted projects often requires interacting with other developers in IRC channels on OFTC. It is recommended to start by getting set up on IRC so that one can ask questions if one encounters issues with other phases of account setup.</p> <p>If you do not know how to connect to OFTC, the <a class="reference external" href="https://www.oftc.net/">Connecting to OFTC</a> document will help. If you’re going to be interacting with others through OFTC on a regular basis, it’s also recommended you <a class="reference external" href="https://www.oftc.net/Services/#register-your-account">Register your IRC Nick</a> since it’s how they’ll know you’re you. This will allow you to reclaim your name later if someone starts using it while you’re not connected, or even (with some additional settings) preventing anyone else from using it at all.</p> <p>You can find the OpenDev community in the <code class="docutils literal notranslate"><span class="pre">#opendev</span></code> IRC channel on OFTC.</p> <p>For further information about the use of IRC in OpenStack, see <a class="reference internal" href="irc.html#irc-guide"><span class="std std-ref">IRC Guide</span></a>.</p> </section> <section id="extra-gerrit-account-setup-steps"> <h3>Extra Gerrit account setup steps<a class="headerlink" href="#extra-gerrit-account-setup-steps" title="Link to this heading">¶</a></h3> <section id="openstack-individual-contributor-license-agreement"> <span id="id1"></span><h4>OpenStack Individual Contributor License Agreement<a class="headerlink" href="#openstack-individual-contributor-license-agreement" title="Link to this heading">¶</a></h4> <p>Projects that are part of OpenStack project require signing the Individual Contributor License Agreement, see <a class="reference external" href="https://docs.openstack.org/contributors/common/setup-gerrit.html#individual-contributor-license-agreement">these detailed instructions</a>.</p> </section> <section id="gerrit-ssh-host-keys"> <span id="id2"></span><h4>Gerrit SSH Host Keys<a class="headerlink" href="#gerrit-ssh-host-keys" title="Link to this heading">¶</a></h4> <p>Careful users may wish to verify the SSH Host key fingerprints for the Gerrit service the first time they connect from a new system. Depending on which key types your client is configured to negotiate, you may see some or all of these listed:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="mi">256</span> <span class="n">SHA256</span><span class="p">:</span><span class="o">/</span><span class="n">aPoKpg</span><span class="o">+</span><span class="mi">804</span><span class="n">wdezs21L9djZ4bOsLudpGF7m7779XVuQ</span> <span class="p">[</span><span class="n">review</span><span class="o">.</span><span class="n">opendev</span><span class="o">.</span><span class="n">org</span><span class="p">]:</span><span class="mi">29418</span> <span class="p">(</span><span class="n">ECDSA</span><span class="p">)</span> <span class="mi">2048</span> <span class="n">SHA256</span><span class="p">:</span><span class="n">RXNl</span><span class="o">/</span><span class="n">GKyDaKiIQ93BoDvrNSKUPFvA1PNeAO9QiirYZU</span> <span class="p">[</span><span class="n">review</span><span class="o">.</span><span class="n">opendev</span><span class="o">.</span><span class="n">org</span><span class="p">]:</span><span class="mi">29418</span> <span class="p">(</span><span class="n">RSA</span><span class="p">)</span> <span class="mi">256</span> <span class="n">SHA256</span><span class="p">:</span><span class="n">lHsyuBxtcAiZeJM</span><span class="o">+</span><span class="n">viHllq52he9JNPqg8FFKv5</span><span class="o">+/</span><span class="n">BJ8</span> <span class="p">[</span><span class="n">review</span><span class="o">.</span><span class="n">opendev</span><span class="o">.</span><span class="n">org</span><span class="p">]:</span><span class="mi">29418</span> <span class="p">(</span><span class="n">ED25519</span><span class="p">)</span> </pre></div> </div> </section> <section id="accessing-gerrit-over-https"> <h4>Accessing Gerrit over HTTPS<a class="headerlink" href="#accessing-gerrit-over-https" title="Link to this heading">¶</a></h4> <p>Git-review normally communicates with Gerrit using SSH over port 29418 with no further configuration needed. However, if you suspect that ssh over non-standards ports might be blocked (or you need to access the web using https) then you can configure git-review to use an https endpoint instead of ssh. Keep in mind that you will need to generate an <a class="reference external" href="https://review.opendev.org/#/settings/http-password">HTTP password in Gerrit</a> to use this connection. You should run the following command before “git review -s”:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">gerrit</span> <span class="n">https</span><span class="p">:</span><span class="o">//<</span><span class="n">username</span><span class="o">></span><span class="nd">@review</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">umbrella</span> <span class="n">repository</span> <span class="n">name</span><span class="o">>/<</span><span class="n">repository</span> <span class="n">name</span><span class="o">>.</span><span class="n">git</span> </pre></div> </div> <p>In case you had already tried to setup git-review and it failed, it might be necessary to remove the Gerrit remote from git:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">rm</span> <span class="n">gerrit</span> </pre></div> </div> </section> </section> </section> <section id="development-workflow"> <h2>Development Workflow<a class="headerlink" href="#development-workflow" title="Link to this heading">¶</a></h2> <section id="working-on-bugs"> <h3>Working on Bugs<a class="headerlink" href="#working-on-bugs" title="Link to this heading">¶</a></h3> <p>Bug reports for a project are generally tracked on Launchpad at <a class="reference external" href="https://bugs.launchpad.net">https://bugs.launchpad.net</a>/<projectname>, or on StoryBoard ( <a class="reference external" href="https://storyboard.openstack.org">https://storyboard.openstack.org</a>). Contributors may review these reports regularly when looking for work to complete.</p> <p>There are 4 key tasks with regards to bugs that anyone can do:</p> <ol class="arabic simple"> <li><p>Confirm new bugs: When a bug is filed, it is set to the “New” status. A “New” bug can be marked “Confirmed” once it has been reproduced and is thus confirmed as genuine.</p></li> <li><p>Solve inconsistencies: Make sure bugs are Confirmed, and if assigned that they are marked “In Progress”</p></li> <li><p>Review incomplete bugs: See if information that caused them to be marked “Incomplete” has been provided, determine if more information is required and provide reminders to the bug reporter if they haven’t responded after 2-4 weeks.</p></li> <li><p>Review stale In Progress bugs: Work with assignee of bugs to determine if the bug is still being worked on, if not, unassign them and mark them back to Confirmed or Triaged.</p></li> </ol> <p>Learn more about working with bugs for various projects at:</p> <p><a class="reference external" href="https://wiki.openstack.org/wiki/BugTriage">https://wiki.openstack.org/wiki/BugTriage</a></p> <p>Bug statuses are documented here:</p> <p><a class="reference external" href="https://docs.openstack.org/project-team-guide/bugs.html">https://docs.openstack.org/project-team-guide/bugs.html</a></p> <p>If you find a bug that you wish to work on, you may assign it to yourself. When you upload a review, include the bug in the commit message for automatic updates back to Launchpad or StoryBoard. The following options are available for Launchpad:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Closes</span><span class="o">-</span><span class="n">Bug</span><span class="p">:</span> <span class="c1">#######</span> <span class="n">Partial</span><span class="o">-</span><span class="n">Bug</span><span class="p">:</span> <span class="c1">#######</span> <span class="n">Related</span><span class="o">-</span><span class="n">Bug</span><span class="p">:</span> <span class="c1">#######</span> </pre></div> </div> <p>and for StoryBoard:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Task</span><span class="p">:</span> <span class="c1">######</span> <span class="n">Story</span><span class="p">:</span> <span class="c1">######</span> </pre></div> </div> <p>Mentioning the story will create a handy link to the story from gerrit, and link to the gerrit patch in StoryBoard. Mentioning the task will change the task status in StoryBoard to ‘review’ while the patch is in review, and then ‘merged’ once the patch is merged. When all tasks in a story are marked ‘merged’, the story will automatically change status from ‘active’ to ‘merged’. If the patch is abandoned, the task status will change back to ‘todo’. It’s currently best to note both story and task so that the task status will update and people will be able to find the related story.</p> <p>Also see the <a class="reference external" href="https://wiki.openstack.org/wiki/GitCommitMessages#Including_external_references">Including external references</a> section of the OpenStack Git Commit Good Practices wiki page.</p> </section> <section id="working-on-specifications-and-blueprints"> <h3>Working on Specifications and Blueprints<a class="headerlink" href="#working-on-specifications-and-blueprints" title="Link to this heading">¶</a></h3> <p>Many OpenStack project teams have a <projectteam>-specs repository which is used to hold approved design specifications for additions and changes to the project team’s code repositories.</p> <p>The layout of the repository will typically be something like:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">specs</span><span class="o">/<</span><span class="n">release</span><span class="o">>/</span> </pre></div> </div> <p>It may also have subdirectories to make clear which specifications are approved and which have already been implemented:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">specs</span><span class="o">/<</span><span class="n">release</span><span class="o">>/</span><span class="n">approved</span> <span class="n">specs</span><span class="o">/<</span><span class="n">release</span><span class="o">>/</span><span class="n">implemented</span> </pre></div> </div> <p>You can typically find an example spec in <code class="docutils literal notranslate"><span class="pre">specs/template.rst</span></code>.</p> <p>Check the repository for the project team you’re working on for specifics about repository organization.</p> <p>Specifications are proposed for a given release by adding them to the <code class="docutils literal notranslate"><span class="pre">specs/<release></span></code> directory and posting it for review. The implementation status of a blueprint for a given release can be found by looking at the blueprint in Launchpad. Not all approved blueprints will get fully implemented.</p> <p>Specifications have to be re-proposed for every release. The review may be quick, but even if something was previously approved, it should be re-reviewed to make sure it still makes sense as written.</p> <p>Historically, Launchpad blueprints were used to track the implementation of these significant features and changes in OpenStack. For many project teams, these Launchpad blueprints are still used for tracking the current status of a specification. For more information, see <a class="reference external" href="https://wiki.openstack.org/wiki/Blueprints">the Blueprints wiki page</a>.</p> <p>View all approved project team’s specifications at <a class="reference external" href="https://specs.openstack.org/">https://specs.openstack.org/</a>.</p> </section> <section id="starting-a-change"> <h3>Starting a change<a class="headerlink" href="#starting-a-change" title="Link to this heading">¶</a></h3> <p>The <a class="reference internal" href="gettingstarted.html#getting-started"><span class="std std-ref">Getting Started</span></a> page explains how to originally clone and prepare a git repository. This only has to be done once, as you can reuse the cloned repository for multiple changes.</p> <p>Before creating your topic branch, just make sure you have the latest upstream changes:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">update</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span> <span class="n">git</span> <span class="n">pull</span> <span class="o">--</span><span class="n">ff</span><span class="o">-</span><span class="n">only</span> <span class="n">origin</span> <span class="n">master</span> </pre></div> </div> </section> <section id="git-branch-names"> <h3>Git branch names<a class="headerlink" href="#git-branch-names" title="Link to this heading">¶</a></h3> <p>You may pick any name for your git branch names. By default, it will be reused as the topic for your change in Gerrit:</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>Best practices recommend, if you are working on a specific blueprint, to name your topic branch <code class="docutils literal notranslate"><span class="pre">bp/BLUEPRINT</span></code> where BLUEPRINT is the name of a blueprint in Launchpad (for example, <code class="docutils literal notranslate"><span class="pre">bp/authentication</span></code>). The general convention when working on bugs is to name the branch <code class="docutils literal notranslate"><span class="pre">bug/BUG-NUMBER</span></code> (for example, <code class="docutils literal notranslate"><span class="pre">bug/1234567</span></code>).</p> <p>If you want to use a different gerrit topic name from the git branch name, you can use the following command to submit your change:</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">t</span> <span class="n">TOPIC</span> </pre></div> </div> </section> <section id="committing-changes"> <h3>Committing changes<a class="headerlink" href="#committing-changes" title="Link to this heading">¶</a></h3> <p><a class="reference external" href="https://wiki.openstack.org/wiki/GitCommitMessages">Git commit messages</a> should start with a short 50 character or less summary in a single paragraph. The following paragraph(s) should explain the change in more detail.</p> <p>If your changes addresses a blueprint or a bug, be sure to mention them in the commit message using the following syntax:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Implements</span><span class="p">:</span> <span class="n">blueprint</span> <span class="n">BLUEPRINT</span> <span class="n">Closes</span><span class="o">-</span><span class="n">Bug</span><span class="p">:</span> <span class="c1">####### (Partial-Bug or Related-Bug are options)</span> </pre></div> </div> <p>For example:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Adds</span> <span class="n">keystone</span> <span class="n">support</span> <span class="o">...</span><span class="n">Long</span> <span class="n">multiline</span> <span class="n">description</span> <span class="n">of</span> <span class="n">the</span> <span class="n">change</span><span class="o">...</span> <span class="n">Implements</span><span class="p">:</span> <span class="n">blueprint</span> <span class="n">authentication</span> <span class="n">Closes</span><span class="o">-</span><span class="n">Bug</span><span class="p">:</span> <span class="c1">#123456</span> <span class="n">Change</span><span class="o">-</span><span class="n">Id</span><span class="p">:</span> <span class="n">I4946a16d27f712ae2adf8441ce78e6c0bb0bb657</span> </pre></div> </div> <p>Note that in most cases the Change-Id line should be automatically added by a Gerrit commit hook installed by git-review. If you already made the commit and the Change-Id was not added, do the Gerrit setup step and run: <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--amend</span></code>. The commit hook will automatically add the Change-Id when you finish amending the commit message, even if you don’t actually make any changes. Do not change the Change-Id when amending a change as that will confuse Gerrit.</p> <p>Make your changes, commit them, and submit them for review:</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> <div class="admonition note"> <p class="admonition-title">Note</p> <p>Do not check in changes on your master branch. Doing so will cause merge commits when you pull new upstream changes, and merge commits will not be accepted by Gerrit.</p> </div> </section> <section id="using-signed-off-by"> <h3>Using Signed-off-by<a class="headerlink" href="#using-signed-off-by" title="Link to this heading">¶</a></h3> <p>Projects may require the use of a <code class="docutils literal notranslate"><span class="pre">Signed-off-by</span></code>, and even if they do not, you are welcome to include <code class="docutils literal notranslate"><span class="pre">Signed-off-by</span></code> in your commits. By doing so, you are certifying that the following is true:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Developer</span><span class="s1">'s Certificate of Origin 1.1</span> <span class="n">By</span> <span class="n">making</span> <span class="n">a</span> <span class="n">contribution</span> <span class="n">to</span> <span class="n">this</span> <span class="n">project</span><span class="p">,</span> <span class="n">I</span> <span class="n">certify</span> <span class="n">that</span><span class="p">:</span> <span class="p">(</span><span class="n">a</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="n">was</span> <span class="n">created</span> <span class="ow">in</span> <span class="n">whole</span> <span class="ow">or</span> <span class="ow">in</span> <span class="n">part</span> <span class="n">by</span> <span class="n">me</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="n">the</span> <span class="n">right</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">it</span> <span class="n">under</span> <span class="n">the</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="n">indicated</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">file</span><span class="p">;</span> <span class="ow">or</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="ow">is</span> <span class="n">based</span> <span class="n">upon</span> <span class="n">previous</span> <span class="n">work</span> <span class="n">that</span><span class="p">,</span> <span class="n">to</span> <span class="n">the</span> <span class="n">best</span> <span class="n">of</span> <span class="n">my</span> <span class="n">knowledge</span><span class="p">,</span> <span class="ow">is</span> <span class="n">covered</span> <span class="n">under</span> <span class="n">an</span> <span class="n">appropriate</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="n">the</span> <span class="n">right</span> <span class="n">under</span> <span class="n">that</span> <span class="n">license</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">that</span> <span class="n">work</span> <span class="k">with</span> <span class="n">modifications</span><span class="p">,</span> <span class="n">whether</span> <span class="n">created</span> <span class="ow">in</span> <span class="n">whole</span> <span class="ow">or</span> <span class="ow">in</span> <span class="n">part</span> <span class="n">by</span> <span class="n">me</span><span class="p">,</span> <span class="n">under</span> <span class="n">the</span> <span class="n">same</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span> <span class="p">(</span><span class="n">unless</span> <span class="n">I</span> <span class="n">am</span> <span class="n">permitted</span> <span class="n">to</span> <span class="n">submit</span> <span class="n">under</span> <span class="n">a</span> <span class="n">different</span> <span class="n">license</span><span class="p">),</span> <span class="k">as</span> <span class="n">indicated</span> <span class="ow">in</span> <span class="n">the</span> <span class="n">file</span><span class="p">;</span> <span class="ow">or</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="n">The</span> <span class="n">contribution</span> <span class="n">was</span> <span class="n">provided</span> <span class="n">directly</span> <span class="n">to</span> <span class="n">me</span> <span class="n">by</span> <span class="n">some</span> <span class="n">other</span> <span class="n">person</span> <span class="n">who</span> <span class="n">certified</span> <span class="p">(</span><span class="n">a</span><span class="p">),</span> <span class="p">(</span><span class="n">b</span><span class="p">)</span> <span class="ow">or</span> <span class="p">(</span><span class="n">c</span><span class="p">)</span> <span class="ow">and</span> <span class="n">I</span> <span class="n">have</span> <span class="ow">not</span> <span class="n">modified</span> <span class="n">it</span><span class="o">.</span> <span class="p">(</span><span class="n">d</span><span class="p">)</span> <span class="n">I</span> <span class="n">understand</span> <span class="ow">and</span> <span class="n">agree</span> <span class="n">that</span> <span class="n">this</span> <span class="n">project</span> <span class="ow">and</span> <span class="n">the</span> <span class="n">contribution</span> <span class="n">are</span> <span class="n">public</span> <span class="ow">and</span> <span class="n">that</span> <span class="n">a</span> <span class="n">record</span> <span class="n">of</span> <span class="n">the</span> <span class="n">contribution</span> <span class="p">(</span><span class="n">including</span> <span class="nb">all</span> <span class="n">personal</span> <span class="n">information</span> <span class="n">I</span> <span class="n">submit</span> <span class="k">with</span> <span class="n">it</span><span class="p">,</span> <span class="n">including</span> <span class="n">my</span> <span class="n">sign</span><span class="o">-</span><span class="n">off</span><span class="p">)</span> <span class="ow">is</span> <span class="n">maintained</span> <span class="n">indefinitely</span> <span class="ow">and</span> <span class="n">may</span> <span class="n">be</span> <span class="n">redistributed</span> <span class="n">consistent</span> <span class="k">with</span> <span class="n">this</span> <span class="n">project</span> <span class="ow">or</span> <span class="n">the</span> <span class="nb">open</span> <span class="n">source</span> <span class="n">license</span><span class="p">(</span><span class="n">s</span><span class="p">)</span> <span class="n">involved</span><span class="o">.</span> </pre></div> </div> <p>A <code class="docutils literal notranslate"><span class="pre">Signed-off-by</span></code> header takes the following form in a commit message:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Signed</span><span class="o">-</span><span class="n">off</span><span class="o">-</span><span class="n">by</span><span class="p">:</span> <span class="n">Full</span> <span class="n">Name</span> <span class="o"><</span><span class="n">email</span><span class="nd">@example</span><span class="o">.</span><span class="n">com</span><span class="o">></span> </pre></div> </div> <p>If you add the <code class="docutils literal notranslate"><span class="pre">-s</span></code> option to <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code>, this header will be added automatically:</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">s</span> </pre></div> </div> </section> <section id="running-unit-tests"> <h3>Running Unit Tests<a class="headerlink" href="#running-unit-tests" title="Link to this heading">¶</a></h3> <p>Before submitting your change, you should test it. To learn how to run python based unit tests in OpenStack projects see <a class="reference external" href="https://docs.openstack.org/project-team-guide/project-setup/python.html#running-python-unit-tests">Running Python Unit Tests</a></p> </section> <section id="previewing-a-change"> <h3>Previewing a Change<a class="headerlink" href="#previewing-a-change" title="Link to this heading">¶</a></h3> <p>Before submitting your change, you should make sure that your change does not contain the files or lines you do not explicitly change:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">show</span> </pre></div> </div> </section> <section id="submitting-a-change-for-review"> <h3>Submitting a Change for Review<a class="headerlink" href="#submitting-a-change-for-review" title="Link to this heading">¶</a></h3> <p>Once you have committed a change to your local repository, all you need to do to send it to Gerrit for code review is run:</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> <p>When that completes, automated tests will run on your change and other developers will peer review it.</p> </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. Gerrit knows that 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 id="understanding-changes-and-patch-sets"> <h4>Understanding Changes and Patch Sets<a class="headerlink" href="#understanding-changes-and-patch-sets" title="Link to this heading">¶</a></h4> <p>It’s important to understand how Gerrit handles changes and patch sets. Gerrit combines the Change-Id in the commit message, the project, and the target branch to uniquely identify a change.</p> <p>A new patch set is determined by any modification in the commit hash. When a change is initially pushed up it only has one patch set. When an update is done for that change, <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--amend</span></code> will change the most current commit’s hash because it is essentially a new commit with the changes from the previous state combined with the new changes added. Since it has a new commit hash, once a <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">review</span></code> is successfully processed, a new patch set appears in Gerrit.</p> <p>Since a patch set is determined by a modification in the commit hash, many git commands will cause new patch sets. Three common ones that do this are:</p> <ul class="simple"> <li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--amend</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">rebase</span></code></p></li> <li><p><code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">cherry-pick</span></code></p></li> </ul> <p>As long as you leave the “Change-Id” line in the commit message alone and continue to propose the change to the same target branch, Gerrit will continue to associate the new commit with the already existing change, so that reviewers are able to see how the change evolves in response to comments.</p> </section> </section> <section id="squashing-changes"> <h3>Squashing Changes<a class="headerlink" href="#squashing-changes" title="Link to this heading">¶</a></h3> <p>If you have made many small commits, you should squash them so that they do not show up in the public repository. Remember: each commit becomes a change in Gerrit, and must be approved separately. If you are making one “change” to the project, squash your many “checkpoint” commits into one commit for public consumption. Here’s how:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span> <span class="n">git</span> <span class="n">pull</span> <span class="n">origin</span> <span class="n">master</span> <span class="n">git</span> <span class="n">checkout</span> <span class="n">TOPIC</span><span class="o">-</span><span class="n">BRANCH</span> <span class="n">git</span> <span class="n">rebase</span> <span class="o">-</span><span class="n">i</span> <span class="n">master</span> </pre></div> </div> <p>Use the editor to squash any commits that should not appear in the public history. If you want one change to be submitted to Gerrit, you should only have one “pick” line at the end of this process. After completing this, you can prepare your public commit message(s) in your editor. You start with the commit message from the commit that you picked, and it should have a Change-Id line in the message. Be sure to leave that Change-Id line in place when editing.</p> <p>Once the commit history in your branch looks correct, run git review to submit your changes to Gerrit.</p> </section> <section id="adding-a-dependency"> <h3>Adding a Dependency<a class="headerlink" href="#adding-a-dependency" title="Link to this heading">¶</a></h3> <p>When you want to start new work that is based on the commit under the review, you can add the commit as a dependency.</p> <p>Fetch change under review and check out branch based on that change:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git review -d $PARENT_CHANGE_NUMBER git checkout -b $DEV_TOPIC_BRANCH </pre></div> </div> <p>Edit files, add files to git:</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="n">git</span> <span class="n">review</span> </pre></div> </div> <div class="admonition note"> <p class="admonition-title">Note</p> <p>git review rebases the existing change (the dependency) and the new commit if there is a conflict against the branch they are being proposed to. Typically this is desired behavior as merging cannot happen until these conflicts are resolved. If you don’t want to deal with new patchsets in the existing change immediately you can pass the <code class="docutils literal notranslate"><span class="pre">-R</span></code> option to git review in the last step above to prevent rebasing. This requires future rebasing to resolve conflicts.</p> </div> <p>If the commit your work depends on is updated, and you need to get the latest patchset from the depended commit, you can do the following.</p> <p>Fetch and checkout the parent change:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git review -d $PARENT_CHANGE_NUMBER </pre></div> </div> <p>Cherry-pick your commit on top of it:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>git review -x $CHILD_CHANGE_NUMBER </pre></div> </div> <p>Submit rebased change for 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> <p>The note for the previous example applies here as well. Typically you want the rebase behavior in git review. If you would rather postpone resolving merge conflicts you can use git review <code class="docutils literal notranslate"><span class="pre">-R</span></code> as the last step above.</p> </section> <section id="rebasing-a-commit"> <h3>Rebasing a commit<a class="headerlink" href="#rebasing-a-commit" title="Link to this heading">¶</a></h3> <p>Sometimes the target branch you are working on has changed, which can create a merge conflict with your patch. In this case, you need to rebase your commit on top of the current state of the branch. This rebase needs to be done manually:</p> <ol class="arabic"> <li><p>Checkout and update master:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>checkout<span class="w"> </span>master <span class="gp">$ </span>git<span class="w"> </span>remote<span class="w"> </span>update </pre></div> </div> </li> <li><p>Checkout the working branch and rebase on master:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>review<span class="w"> </span>-d<span class="w"> </span><span class="m">180503</span> <span class="gp">$ </span>git<span class="w"> </span>rebase<span class="w"> </span>origin/master </pre></div> </div> </li> <li><p>If git indicates there are merge conflicts, view the affected files:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>status </pre></div> </div> </li> <li><p>Edit the listed files to fix conflicts, then add the modified files:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>add<span class="w"> </span><file1><span class="w"> </span><file2><span class="w"> </span><file3> </pre></div> </div> </li> <li><p>Confirm that all conflicts are resolved, then continue the rebase:</p> <div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>git<span class="w"> </span>status <span class="gp">$ </span>git<span class="w"> </span>rebase<span class="w"> </span>--continue </pre></div> </div> </li> </ol> </section> <section id="cross-repository-dependencies"> <h3>Cross-Repository Dependencies<a class="headerlink" href="#cross-repository-dependencies" title="Link to this heading">¶</a></h3> <p>If your change has a dependency on a change outside of that repository, like a change for another repository or some manual setup, you have to ensure that the change merge at the right time.</p> <p>For a change depending on a manual setup, mark your change with the “Work in Progress” label until the manual setup is done. A core reviewer might also block an important change with a -2 so that it does not get merged accidentally before the manual setup is done.</p> <p>If your change has a dependency on a change in another repository, you can use cross-repo dependencies (CRD) in Zuul:</p> <ul class="simple"> <li><p>To use them, include “Depends-On: <gerrit-change-url>” in the footer of your commit message. Use the permalink of the change. This is output by Gerrit when running git-review on the change, or you can find it in the top-left corner of the Gerrit web interface. Where it says “Change ###### - Needs …” the number is the link to the change; you can copy and paste that URL. A patch can also depend on multiple changes as explained in <a class="reference internal" href="#multiple-changes"><span class="std std-ref">Multiple Changes</span></a>.</p></li> <li><p>These are one-way dependencies only – do not create a cycle.</p></li> </ul> <section id="gate-pipeline"> <h4>Gate Pipeline<a class="headerlink" href="#gate-pipeline" title="Link to this heading">¶</a></h4> <p>When Zuul sees CRD changes, it serializes them in the usual manner when enqueuing them into a pipeline. This means that if change A depends on B, then when they are added to the gate pipeline, B will appear first and A will follow. If tests for B fail, both B and A will be removed from the pipeline, and it will not be possible for A to merge until B does.</p> <p>Note that if changes with CRD do not share a change queue (such as the “integrated gate”), then Zuul is unable to enqueue them together, and the first will be required to merge before the second is enqueued.</p> </section> <section id="check-pipeline"> <h4>Check Pipeline<a class="headerlink" href="#check-pipeline" title="Link to this heading">¶</a></h4> <p>When changes are enqueued into the check pipeline, all of the related dependencies (both normal git-dependencies that come from parent commits as well as CRD changes) appear in a dependency graph, as in the gate pipeline. This means that even in the check pipeline, your change will be tested with its dependency. So changes that were previously unable to be fully tested until a related change landed in a different repo may now be tested together from the start.</p> <p>All of the changes are still independent (so you will note that the whole pipeline does not share a graph as in the gate pipeline), but for each change tested, all of its dependencies are visually connected to it, and they are used to construct the git references that Zuul uses when testing. When looking at this graph on the <a class="reference external" href="https://zuul.opendev.org/">Zuul status page</a>, you will note that the dependencies show up as grey dots, while the actual change tested shows up as red or green. This is to indicate that the grey changes are only there to establish dependencies. Even if one of the dependencies is also being tested, it will show up as a grey dot when used as a dependency, but separately and additionally will appear as its own red or green dot for its test.</p> </section> <section id="multiple-changes"> <span id="id3"></span><h4>Multiple Changes<a class="headerlink" href="#multiple-changes" title="Link to this heading">¶</a></h4> <p>A Gerrit URL refers to a single change on a single branch, so if your change depends on multiple changes, or the same change on multiple branches of a project, you will need to explicitly list each URL. Simply add another “Depends-On:” line to the footer for each additional change.</p> </section> <section id="cycles"> <h4>Cycles<a class="headerlink" href="#cycles" title="Link to this heading">¶</a></h4> <p>If a cycle is created by use of CRD, Zuul will abort its work very early. There will be no message in Gerrit and no changes that are part of the cycle will be enqueued into any pipeline. This is to protect Zuul from infinite loops. The developers hope that they can improve this to at least leave a message in Gerrit in the future. But in the meantime, please be cognizant of this and do not create dependency cycles with Depends-On lines.</p> </section> <section id="limitations-and-caveats"> <h4>Limitations and Caveats<a class="headerlink" href="#limitations-and-caveats" title="Link to this heading">¶</a></h4> <p>Keep in mind that these dependencies are dependencies on changes in other repositories. Thus, a Depends-on only enforces an ordering but is not visible otherwise especially in these cases:</p> <ul> <li><p>Changes for the CI infrastructure like changes <code class="docutils literal notranslate"><span class="pre">openstack/project-config</span></code> are never tested in a production simulated environment. So, if one of the changes adjusts the job definitions or creates a new job, a Depends-On will not test the new definition, the CI infrastructure change needs to merge to master and be in production to be fully evaluated.</p></li> <li><p>If a test job installs packages from PyPI and not via source, be aware that the package from PyPI will always be used, a Depends-On will not cause a modified package to be used instead of installing from PyPI.</p> <p>As an example, if you are testing a change in python-novaclient that needs a change in python-keystoneclient, you add a Depends-On in the python-novaclient change. If a python-novaclient job installs python-keystoneclient from PyPI, the Depends-On will not have any effect since the PyPI version is used. If a python-novaclient job installs python-keystoneclient from source, the checked out source will have the change applied.</p> </li> </ul> <p>Do not add a Depends-On an abandoned change, your change will never merge.</p> <p>If you backport a change to another branch, it will recieve a new URL. If you need to additionally depend on the backported change, you will need to amend the commit message to add another Depends-On footer.</p> <p>A change that is dependent on another can be approved before the dependent change merges. If the repositories share the gate queue, it will merge automatically after the dependent change merged. But if the repositories do not share the gate queue, it will not merge automatically when the dependent change has merged, even a <code class="docutils literal notranslate"><span class="pre">recheck</span></code> will not help. Zuul waits for a status change and does not see it. The change needs another approval or a toggle of the approval, toggle means removing the approval and readding it again.</p> </section> </section> </section> <section id="code-review"> <h2>Code Review<a class="headerlink" href="#code-review" title="Link to this heading">¶</a></h2> <p>Log in to <a class="reference external" href="https://review.opendev.org/">https://review.opendev.org/</a> to see proposed changes, and review them.</p> <p>To provide a review for a proposed change in the Gerrit UI, click on the <code class="docutils literal notranslate"><span class="pre">Reply...</span></code> button. In the code review, you can add a message, as well as a vote (+1,0,-1).</p> <p>It’s also possible to add comments to specific lines in the file, for giving context to the comment. For that look at the diff of changes done in the file (click the file name), and click on the line number for which you want to add the inline comment. After you add one or more inline comments, you still have to send the Review message (see above, with or without text and vote). Prior to sending the inline comments in a review comment the inline comments are stored as Drafts in your browser. Other reviewers can only see them after you have submitted them as a comment on the patchset.</p> <p>Any developer may propose or comment on a change (including voting +1/0/-1 on it). A vote of +2 is allowed from core reviewers, and should be used to indicate that they are a core reviewer and are leaving a vote that should be counted as such.</p> <p>Some OpenDev hosted projects, like many OpenStack project teams, have a policy requiring two positive reviews from core reviewers.</p> <p>When a review has enough +2 reviews and one of the core team believes it is ready to be merged, he or she should leave a +1 vote in the “Workflow” category. You may do so by clicking the “Review” button again, with or without changing your code review vote and optionally leaving a comment. When a +1 Approved review is received, Zuul will run tests on the change, and if they pass, it will be merged.</p> <p>A green checkmark indicates that the review has met the requirement for that category. Under “Code-Review”, only one +2 gets the green check.</p> <p>For more details on reviews in Gerrit, check the <a class="reference external" href="https://review.opendev.org/Documentation/intro-quick.html#_reviewing_the_change">Gerrit documentation</a>.</p> <section id="automated-testing"> <span id="id4"></span><h3>Automated Testing<a class="headerlink" href="#automated-testing" title="Link to this heading">¶</a></h3> <p>When a new patchset is uploaded to Gerrit, that project’s “check” tests are run on the patchset by Zuul. Once completed the test results are reported to Gerrit by Zuul in the form of a Verified: +/-1 vote. After code reviews have been completed and a change receives an Approved: +1 vote that project’s “gate” tests are run on the change by Zuul. Zuul reports the results of these tests back to Gerrit in the form of a Verified: +/-2 vote. Code merging will only occur after the gate tests have passed successfully and received a Verified: +2. You can view the state of tests currently being run on the <a class="reference external" href="https://zuul.opendev.org/">Zuul Status page</a>.</p> <p>If a change fails tests in Zuul, please follow the steps below:</p> <ol class="arabic"> <li><p>Zuul leaves a comment in the review with links to the log files for the test run. Follow those links and examine the output from the test. It will include a console log, and in the case of unit tests, HTML output from the test runner, or in the case of a devstack-gate test, it may contain quite a large number of system logs.</p></li> <li><p>Examine the console log or other relevant log files to determine the cause of the error. If it is related to your change, you should fix the problem and upload a new patchset. Do not use “recheck”.</p></li> <li><p>It is possible that the CI infrastructure may be having some issues which are causing your tests to fail. You can verify the status of the OpenDev infrastructure by doing the following:</p> <ul class="simple"> <li><p><a class="reference external" href="https://wiki.openstack.org/wiki/Infrastructure_Status">https://wiki.openstack.org/wiki/Infrastructure_Status</a></p></li> <li><p><a class="reference external" href="https://twitter.com/openstackinfra">@OpenStackInfra</a> on Twitter.</p></li> <li><p>the topic in your project’s IRC channel (or <code class="docutils literal notranslate"><span class="pre">#opendev</span></code>)</p></li> </ul> <div class="admonition note"> <p class="admonition-title">Note</p> <p>If a job fails in the automated testing system with the status of <code class="docutils literal notranslate"><span class="pre">POST_FAILURE</span></code> rather than a normal <code class="docutils literal notranslate"><span class="pre">FAILURE</span></code>, it could either be that your tests resulted with the system under test losing network connectivity or an issue with the automated testing system.</p> <p>If you are seeing repeated <code class="docutils literal notranslate"><span class="pre">POST_FAILURE</span></code> reports with no indication of problems in the CI system, make sure that your tests are not impacting the network of the system.</p> </div> </li> <li><p>It may be the case that the problem is due to non-deterministic behavior unrelated to your change that has already merged. In this situation, you can help other developers and focus the attention of QA, CI, and developers working on a fix by performing the following steps:</p> <ol class="arabic"> <li><p>For OpenStack projects, check <a class="reference external" href="https://docs.openstack.org/contributors/code-and-documentation/elastic-recheck.html">elastic-recheck</a> to see whether the bug is already identified and if not, add it.</p> <p>If your error is not there, then:</p> </li> <li><p>Identify which project or projects are affected, and search for a related bug on Launchpad. You can search for bugs affecting all OpenStack Projects here: <a class="reference external" href="https://bugs.launchpad.net/openstack/">https://bugs.launchpad.net/openstack/</a> If you do not find an existing bug, file a new one (be sure to include the error message and a link to the logs for the failure). If the problem is due to an infrastructure problem (such as Zuul or Gerrit), file (or search for) the bug against the openstack-gate project.</p></li> </ol> </li> <li><p>It may also happen that the CI infrastructure somehow cannot finish a job and restarts it. If this happens several times, the job is marked as failed with a message of <code class="docutils literal notranslate"><span class="pre">RETRY_LIMIT</span></code>. Usually this means that network connectivity for the job was lost and the change itself causes the job node to become unreachable consistently.</p></li> <li><p>To re-run check or gate jobs, leave a comment on the review with the form “recheck”.</p></li> </ol> <p>A patchset has to be approved to run tests in the gate pipeline. If the patchset has failed in the gate pipeline (it will have been approved to get into the gate pipeline) a recheck will first run the check jobs and if those pass, it will again run the gate jobs. There is no way to only run the gate jobs, the check jobs will first be run again.</p> <p>More information on debugging automated testing failures can be found in the following recordings:</p> <ul class="simple"> <li><p><a class="reference external" href="https://www.youtube.com/watch?v=sa67J6yMYZ0">Tales From The Gate</a></p></li> <li><p><a class="reference external" href="https://www.youtube.com/watch?v=fowBDdLGBlU">Debugging Failures in the OpenStack Gate</a></p></li> </ul> </section> <section id="post-processing"> <h3>Post Processing<a class="headerlink" href="#post-processing" title="Link to this heading">¶</a></h3> <p>After patches land, jobs can be run in the post queue. Finding build logs for these jobs works a bit differently to the results of the pre-merge check and gate queues.</p> <p>For jobs in the post queue, logs are found via the builds tab of <a class="reference external" href="https://zuul.opendev.org/">https://zuul.opendev.org/</a>, for example to search for post jobs of the openstack tenant, go to the <a class="reference external" href="http://zuul.opendev.org/t/openstack/builds?pipeline=post">Zuul openstack build tab</a> .</p> </section> <section id="peer-review"> <h3>Peer Review<a class="headerlink" href="#peer-review" title="Link to this heading">¶</a></h3> <p>Anyone can be a reviewer: participating in the review process is a great way to learn about social norms and the development processes.</p> <p>General review flow:</p> <ol class="arabic"> <li><p>Review is a conversation that works best when it flows back and forth. Submitters need to be responsive to questions asked in comments, even if the score is <cite>+0</cite> from the reviewer. Likewise, reviewers should not use a negative score to elicit a response if they are not sure the patch should be changed before merging.</p> <p>For example, if there is a patch submitted which a reviewer cannot fully understand because there are changes that aren’t documented in the commit message or code documentation, this is a good time to issue a negative score. Patches need to be clear in their commit message and documentation.</p> <p>As a counter-example, a patch which is making use of a new library, which the reviewer has never used before, should not elicit a negative score from the reviewer with a question like “Is this library using standard python sockets for communication?” That is a question the reviewer can answer themselves, and which should not hold up the review process while the submitter explains things. Either the author or a reviewer should try to add a review comment answering such questions, unless they indicate a need to better extend the commit message, code comments, docstrings or accompanying documentation files.</p> </li> <li><p>In almost all cases, a negative review should be accompanied by clear instructions for the submitter how they might fix the patch.</p></li> </ol> <p>There may be more specific items to be aware of inside the projects’ documentation for contributors.</p> <p>Contributors may notice a review that has several +1’s from other reviewers, passes the functional tests, etc. but the code still has not been merged. As only core contributors can approve code for merging, you can help things along by getting a core reviewer’s attention in IRC (never on the mailing lists) and letting them know there is a changeset with lots of positive reviews and needs final approval.</p> </section> <section id="work-in-progress"> <h3>Work in Progress<a class="headerlink" href="#work-in-progress" title="Link to this heading">¶</a></h3> <p>To get early feedback on a change which is not fully finished yet, you can submit a change to Gerrit and mark it as “Work in Progress” (WIP).</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>The OpenDev Gerrit system does not support drafts, use “Work in Progress” instead. Draft changes have been disabled because people assume they are private when they are not. They also create confusion if child changes are not drafts. Additionally it is difficult to run CI on them. It is better to assume changes are public and mark the not yet ready state.</p> </div> <p>To do so, after submitting a change to Gerrit in usual way (<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">review</span></code>), You should go to Gerrit, and do <a class="reference internal" href="#code-review">Code Review</a> of your own change while setting “Workflow” vote to “-1”, which marks the change as WIP.</p> <p>This allows others to review the change, while at the same time blocking it from being merged, as you already plan to continue working on it.</p> <div class="admonition note"> <p class="admonition-title">Note</p> <p>After uploading a new patchset, this -1 (WIP) vote disappears. So if you still plan to do additional changes, do not forget to set Workflow to -1 on the new patchset.</p> </div> </section> </section> <section id="merging"> <h2>Merging<a class="headerlink" href="#merging" title="Link to this heading">¶</a></h2> <p>Once a change has been approved and passed the gate jobs, Gerrit automatically merges the latest patchset.</p> <p>Each patchset gets merged to the head of the branch before testing it. If Gerrit cannot merge a patchset, it will give a -1 review and add a comment notifying of merge failure.</p> <p>Each time a change merges, the “merge-check” pipeline verifies that all open changes on the same project are still mergeable. If any job is not mergeable, Zuul will give a -1 review and add a comment notifying of merge failure.</p> <p>After a change is merged, project-specific post jobs are run. Most often the post jobs publish documentation, run coverage, or send strings to the translation server.</p> <section id="project-gating"> <h3>Project Gating<a class="headerlink" href="#project-gating" title="Link to this heading">¶</a></h3> <p>Project gating refers to the process of running regression tests before a developer’s patchset is merged. The intent of running regression tests is to validate that new changes submitted against the source code repository will not introduce new bugs. Gating prevents regressions by ensuring that a series of tests pass successfully before allowing a patchset to be merged into the mainline of development.</p> <p>The system used for gating is Zuul, which listens to the Gerrit event stream and is configured with YAML files to define a series of tests to be run in response to an event.</p> <p>The jobs in the gate queue are executed once a core reviewer approves a change (using a +1 Workflow vote) and a verified +1 vote exist. When approving, at least one +2 Code-Review vote needs to exist (can be given by core reviewer when approving). The convention is that two +2 Code-Reviews are needed for approving.</p> <p>Once all of the jobs report success on an approved patchset in the configured gate pipeline, then Gerrit will merge the code into trunk.</p> <p>Besides running the gate tests, the gate pipeline determines the order of changes to merge across multiple projects. The changes are tested and merged in this order, so that for each change the state of all other repositories can be identified.</p> <p>Additional information about project gating and Zuul can be found in the Zuul documentation, located at: <a class="reference external" href="https://zuul-ci.org/docs/zuul/user/gating.html">https://zuul-ci.org/docs/zuul/user/gating.html</a></p> </section> </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"><a class="reference internal" href="gettingstarted.html">Getting Started</a></li> <li class="toctree-l1 current"><a class="current reference internal" href="#">Developer’s Guide</a><ul> <li class="toctree-l2"><a class="reference internal" href="#accounts-creation">Accounts creation</a></li> <li class="toctree-l2"><a class="reference internal" href="#development-workflow">Development Workflow</a></li> <li class="toctree-l2"><a class="reference internal" href="#code-review">Code Review</a></li> <li class="toctree-l2"><a class="reference internal" href="#merging">Merging</a></li> </ul> </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="gettingstarted.html" title="previous chapter">Getting Started</a></li> <li>Next: <a href="irc.html" title="next chapter">IRC 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/developers.rst.txt" rel="nofollow">Page source</a> </div> </body> </html>