| <!--- |
| 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. |
| --> |
| |
| <html> |
| <head> |
| <meta charset="utf-8"> |
| <title>Apache Yetus</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content=""> |
| <meta name="author" content=""> |
| |
| <link href="../../../../assets/css/bootstrap.css" rel="stylesheet"> |
| <link href="../../../../assets/css/bootstrap-theme.css" rel="stylesheet"> |
| <link href="../../../../assets/css/font-awesome.css" rel="stylesheet"> |
| |
| <!-- JS --> |
| <script type="text/javascript" src="../../../../assets/js/jquery-2.1.4.min.js"></script> |
| <script type="text/javascript" src="../../../../assets/js/bootstrap.js"></script> |
| </head> |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-static-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="img-responsive pull-left" href="/"> |
| <img style="max-height: 40px; margin-top: 5px; margin-bottom: 5px;" src="../../../../assets/img/yetus_logo.png" alt="Apache Yetus logo" /> |
| </a> |
| </div> |
| <div class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li><a href="/downloads/">Downloads</a> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="/documentation/0.13.0/">Docs for v0.13.0</a></li> |
| <li><a href="/documentation/0.14.1/">Docs for v0.14.1</a></li> |
| <li><a href="/documentation/0.15.0/">Docs for v0.15.0</a></li> |
| <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</a> |
| </li> |
| <li><a href="/documentation/history/">History of the Project</a> |
| </li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Get Involved <span class="caret"></span></a> |
| <ul class="dropdown-menu" role="menu" aria-labelledby="drop1"> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/mailinglists"><i class="fa fa-commenting"></i> Mailing Lists</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://issues.apache.org/jira/browse/YETUS"><i class="fa fa-bug"></i> JIRA (Bugs)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://gitbox.apache.org/repos/asf/yetus.git"><i class="fa fa-code"></i> Source (Apache)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://github.com/apache/yetus"><i class="fa fa-github-alt"></i> Source (GitHub)</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="/contribute/"><i class="fa fa-code-fork"></i> Contributing</a> |
| </li> |
| <li role="presentation"><a role="menuitem" tabindex="-1" href="https://twitter.com/ApacheYetus"><i class="fa fa-twitter"></i> @ApacheYetus</a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation <b class="caret"></b></a> |
| <ul class="dropdown-menu" role="menu"> |
| <li><a href="https://www.apache.org">Apache Homepage</a> |
| </li> |
| <li><a href="https://www.apache.org/licenses/">Apache License</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li><a href="https://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| </li> |
| </li> |
| </ul> |
| </div> |
| <!--/.nav-collapse --> |
| </div> |
| </div> |
| |
| <div class="container"> |
| <!--- |
| 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. |
| --> |
| |
| <h1 id="basic-precommit">Basic Precommit</h1> |
| |
| <!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" --> |
| |
| <ul> |
| <li><a href="#first-steps">First Steps</a> |
| <ul> |
| <li><a href="#first-steps-output">First Steps Output</a></li> |
| </ul> |
| </li> |
| <li><a href="#resetting-the-repository">Resetting the Repository</a> |
| <ul> |
| <li><a href="#--restrepo-output">–restrepo Output</a></li> |
| </ul> |
| </li> |
| <li><a href="#dirty-workspaces">Dirty Workspaces</a></li> |
| <li><a href="#enabling-features">Enabling Features</a></li> |
| <li><a href="#unit-tests">Unit Tests</a></li> |
| <li><a href="#output-directory">Output Directory</a></li> |
| <li><a href="#build-tool">Build Tool</a></li> |
| <li><a href="#providing-patch-files">Providing Patch Files</a> |
| <ul> |
| <li><a href="#jira">JIRA</a></li> |
| <li><a href="#github">GITHUB</a></li> |
| <li><a href="#gitlab">GITLAB</a></li> |
| <li><a href="#generic-urls">Generic URLs</a></li> |
| </ul> |
| </li> |
| <li><a href="#excluding-files">Excluding Files</a></li> |
| <li><a href="#warn-only-test-results">"Warn-only" Test Results</a></li> |
| <li><a href="#project-specific-capabilities">Project-specific Capabilities</a> |
| <ul> |
| <li><a href="#direct-method">Direct Method</a></li> |
| <li><a href="#project-method">Project Method</a></li> |
| </ul> |
| </li> |
| <li><a href="#fork-bomb-protection">Fork Bomb Protection</a></li> |
| <li><a href="#multijdk">MultiJDK</a></li> |
| <li><a href="#docker">Docker</a></li> |
| <li><a href="#upgrading">Upgrading</a></li> |
| <li><a href="#in-closing">In Closing</a></li> |
| </ul> |
| |
| <!-- /MarkdownTOC --> |
| |
| <h1 id="first-steps">First Steps</h1> |
| |
| <p>A typical local configuration is to have two repositories. One with the code you are working on and another, clean repository. The workflow looks similar to the following:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">cd</span> <workrepo> |
| <span class="nv">$ </span>git format-patch master <span class="o">></span> /tmp/patchfile |
| <span class="nv">$ </span>test-patch <span class="nt">--basedir</span><span class="o">=</span>/some/path/testrepo <span class="nt">--build-tool</span><span class="o">=</span>nobuild /tmp/patchfile |
| </code></pre></div> |
| <ol> |
| <li>In your work repo, generate a patch.</li> |
| <li>Run your patch against the test repository.</li> |
| </ol> |
| |
| <p><code>--basedir</code> sets the location of the repository to use for testing. The <code>/tmp/patchfile</code> is the patch file that is generated by <code>git format-patch</code> or <code>git diff</code> or any number of other types of input.</p> |
| |
| <h2 id="first-steps-output">First Steps Output</h2> |
| |
| <p>When you run it, you should see something similar to this:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--basedir</span><span class="o">=</span>/tmp/yetus.test <span class="nt">--build-tool</span><span class="o">=</span>nobuild /tmp/patchfile |
| /tmp/yetus-14497.22984 has been created |
| Modes: |
| Processing: /tmp/patchfile |
| Patch file /tmp/patchfile copied to /private/tmp/yetus-14497.22984 |
| |
| |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| Confirming git environment |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| |
| |
| |
| Testing patch on master. |
| |
| |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| Determining needed tests |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| |
| |
| <span class="o">(</span>Depending upon input size and number of plug-ins, this may take a <span class="k">while</span><span class="o">)</span> |
| |
| |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| Cleaning the <span class="nb">source </span>tree |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| |
| |
| <span class="nb">cd</span> /tmp/yetus.test |
| <span class="nb">true</span> <span class="o">></span> /private/tmp/yetus-14497.22984/branch-distclean-root.txt 2>&1 |
| Elapsed: 0m 00s |
| |
| |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| Applying patch to master |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| |
| |
| Applying the changes: |
| Sun Jun 9 10:17:17 PDT 2019 |
| <span class="nb">cd</span> /tmp/yetus.test |
| git apply <span class="nt">--binary</span> <span class="nt">-v</span> <span class="nt">--stat</span> <span class="nt">--apply</span> <span class="nt">-p1</span> /private/tmp/yetus-14497.22984/input.patch |
| Applied patch README.md cleanly. |
| README.md | 1 + |
| 1 file changed, 1 insertion<span class="o">(</span>+<span class="o">)</span> |
| |
| Total Elapsed <span class="nb">time</span>: 0m 01s |
| |
| |
| +1 overall |
| |
| ____ _ |
| / ___| _ _ ___ ___ ___ ___ ___| | |
| <span class="se">\_</span>__ <span class="se">\|</span> | | |/ __/ __/ _ <span class="se">\/</span> __/ __| | |
| ___<span class="o">)</span> | |_| | <span class="o">(</span>_| <span class="o">(</span>_| __/<span class="se">\_</span>_ <span class="se">\_</span>_ <span class="se">\_</span>| |
| |____/ <span class="se">\_</span>_,_|<span class="se">\_</span>__<span class="se">\_</span>__<span class="se">\_</span>__||___/___<span class="o">(</span>_<span class="o">)</span> |
| |
| |
| |
| | Vote | Subsystem | Runtime | Comment |
| <span class="o">============================================================================</span> |
| | | | | Prechecks |
| | | | | master Compile Tests |
| | | | | Patch Compile Tests |
| | | | | Other Tests |
| | | | 0m 01s | |
| |
| |
| <span class="o">||</span> Subsystem <span class="o">||</span> Report/Notes <span class="o">||</span> |
| <span class="o">============================================================================</span> |
| | Optional Tests | | |
| | <span class="nb">uname</span> | Darwin <span class="nb">hostname </span>18.6.0 Darwin Kernel Version 18.6.0: Thu Apr 25 23:16:27 PDT 2019<span class="p">;</span> root:xnu-4903.261.4~2/RELEASE_X86_64 x86_64 | |
| | Build tool | nobuild | |
| | git revision | master / 6b94d9df | |
| | modules | C: <span class="nb">.</span> U: <span class="nb">.</span> | |
| | versions | <span class="nv">git</span><span class="o">=</span>2.21.0 | |
| | Powered by | Apache Yetus 0.11.0 https://yetus.apache.org | |
| |
| |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| Finished build. |
| <span class="o">============================================================================</span> |
| <span class="o">============================================================================</span> |
| </code></pre></div> |
| <p><code>test-patch</code> gives extensive information about what it is doing at run time and then provides a report at the end to give a summary about what happened. In this particular case, this output just shows that the patch was applied and that no tests were actually run.</p> |
| |
| <h1 id="resetting-the-repository">Resetting the Repository</h1> |
| |
| <p>After running that command, the test repository will contain the remnants of the build for later debugging. It is inconvenient to instead use:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">cd</span> <workrepo> |
| <span class="nv">$ </span>git format-patch main <span class="o">></span> /tmp/patchfile |
| <span class="nv">$ </span>test-patch <span class="nt">--basedir</span><span class="o">=</span>/some/path/testrepo <span class="nt">--resetrepo</span> <span class="nt">--build-tool</span><span class="o">=</span>nobuild /tmp/patchfile |
| </code></pre></div> |
| <p><code>--resetrepo</code> tells test patch that it can go into <strong>destructive</strong> mode. Destructive mode will wipe out any changes made to that repository, so use it with care!</p> |
| |
| <h2 id="restrepo-output">–restrepo Output</h2> |
| |
| <p>In this particular case, the output will look nearly identical expect for one change:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code>Modes: ResetRepo |
| </code></pre></div> |
| <p>Some features are mostly invisible or auto-detected during runtime. The <code>Modes</code> line provides hints about those features.</p> |
| |
| <h1 id="dirty-workspaces">Dirty Workspaces</h1> |
| |
| <p>An alternative to <code>--resetrepo</code> is the <code>--dirty-workspace</code> flag. It tells test-patch that the repository is not clean and it is ok to continue. This is especially useful on a repository that is in some way 'live,' such as a repository that is actively being used for development.</p> |
| |
| <h1 id="enabling-features">Enabling Features</h1> |
| |
| <p>In general, almost all features are enabled via the plug-in framework. To see what has been enabled, use the <code>--list-plugins</code> option:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--list-plugins</span> |
| </code></pre></div> |
| <p>You should see output similar to this:</p> |
| |
| <div class="highlight"><pre class="highlight plaintext"><code>BUILDTOOLS: |
| nobuild ant autoconf cmake gradle make maven |
| TESTTYPES: |
| asflicense author blanks buf cc checkmake checkstyle dupname golang golangcilint hadolint javac javadoc jshint markdownlint mvnsite pathlen perlcritic pylint revive rubocop scalac scaladoc shellcheck shelldocs test4tests unitveto xml yamllint |
| BUGSYSTEMS: |
| briefreport bugzilla github gitlab htmlout jira junit slack |
| TESTFORMATS: |
| ctest junit tap |
| </code></pre></div> |
| <p>This output shows all of the plug-ins that are available as well as what type of plug-in they are.</p> |
| |
| <ul> |
| <li>BUILDTOOLS - These drive the actual compiling of the source tree.</li> |
| <li>TESTTYPES - Various kinds of tests that precommit can apply to the source, patches, and generated output (object files, etc).</li> |
| <li>BUGSYSTEMS - Integration support for input of patches or output of reports.</li> |
| <li>TESTFORMATS - Types of unit test output that precommit reads.</li> |
| </ul> |
| |
| <p>From this list, the specific plug-ins can be enabled:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span><span class="s2">"ant,maven,shellcheck,xml"</span> <other options> |
| </code></pre></div> |
| <p>As a short-cut, every plug-in may be enabled via the special 'all' type:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span><span class="s2">"all"</span> <other options> |
| </code></pre></div> |
| <p><code>--plugins</code> also allows some basic "arithmetic":</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span><span class="s2">"all,-checkstyle,-spotbugs"</span> <other options> |
| </code></pre></div> |
| <p>This will enable all plug-ins for potential usage, except for <code>checkstyle</code> and <code>spotbugs</code>.</p> |
| |
| <p><strong>NOTE: Many examples in this section will use <code>--plugins=all</code>. Users should set the <code>--plugins</code> option as appropriate.</strong></p> |
| |
| <p>This command will execute basic patch testing using every available plug-in against a patch file stored in "filename":</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">cd</span> <your repo> |
| <span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <other options> <filename> |
| </code></pre></div> |
| <h1 id="unit-tests">Unit Tests</h1> |
| |
| <p>By default, unit tests are not run since they may take a significant amount of time.</p> |
| |
| <p>To turn them on, we need to provide the –run-tests option:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span><span class="nb">cd</span> <your repo> |
| <span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--dirty-workspace</span> <span class="nt">--run-tests</span> <filename> |
| </code></pre></div> |
| <p>This is the same command, but now runs the unit tests.</p> |
| |
| <h1 id="output-directory">Output Directory</h1> |
| |
| <p>After the tests have run, there is a directory that contains all of the <code>test-patch</code> related artifacts. This is generally referred to as the patch directory. By default, <code>test-patch</code> tries to make something off of <code>/tmp</code> to contain this content. Using the <code>--patch-dir</code> option, one can specify exactly which directory to use. This is helpful for automated precommit testing so that <a href="../robots">continuous integration systems</a> knows where to look to gather up the output.</p> |
| |
| <p>For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--patch-dir</span><span class="o">=</span><span class="k">${</span><span class="nv">WORKSPACE</span><span class="k">}</span>/patchdir <span class="nt">--basedir</span><span class="o">=</span><span class="k">${</span><span class="nv">WORKSPACE</span><span class="k">}</span>/source <span class="k">${</span><span class="nv">WORKSPACE</span><span class="k">}</span>/patchfile |
| </code></pre></div> |
| <p>… will trigger <code>test-patch</code> to run in fully automated mode, using <code>${WORKSPACE}/patchdir</code> as its scratch space, <code>${WORKSPACE}/source</code> as the source repository, and <code>${WORKSPACE}/patchfile</code> as the name of the patch to test against. This will always run the unit tests, write answers back to bug systems, remove old, stopped/exited Docker containers after 24 hours and images after 1 week, forcibly use <code>--resetrepo</code>, and more.</p> |
| |
| <p><strong>NOTE: Make sure to add the patch directory to <code>.gitignore</code> if the directory is inside the source tree to avoid deleting it, as <code>test-patch</code> does a <code>git clean</code> to remove untracked files from previous runs.</strong></p> |
| |
| <h1 id="build-tool">Build Tool</h1> |
| |
| <p>Out of the box, <code>test-patch</code> will try to figure out which build tool the project uses. But what if you want to override it? The <code>--build-tool</code> option allows a manual setting:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--build-tool</span><span class="o">=</span>ant <span class="o">(</span>other options<span class="o">)</span> |
| </code></pre></div> |
| <p>will tell <code>test-patch</code> to use <code>ant</code> instead of maven to drive the project.</p> |
| |
| <p>To disable the build tool entirely, use the <code>nobuild</code> setting:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--build-tool</span><span class="o">=</span>nobuild <span class="o">(</span>other options<span class="o">)</span> |
| </code></pre></div> |
| <h1 id="providing-patch-files">Providing Patch Files</h1> |
| |
| <p>NOTE: More in-depth information may be found in the <a href="../bugsystems/">bugsystems</a> section.</p> |
| |
| <h2 id="jira">JIRA</h2> |
| |
| <p>It is a fairly common practice within the Apache community to use Apache's JIRA instance to store potential patches. As a result, <code>test-patch</code> supports providing just a JIRA issue number via the <code>jira</code> plug-in. <code>test-patch</code> will find the <em>last</em> attachment, download it, then process it.</p> |
| |
| <p><strong>NOTE: <code>test-patch</code> expects the patch files to follow a particular naming convention. For complete details<br /> |
| on the naming convention please refer to <a href="../patchnames/">patch-naming-conventions</a></strong></p> |
| |
| <p>For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all HADOOP-9905 <span class="o">(</span>other options<span class="o">)</span> |
| </code></pre></div> |
| <p>… will process the patch file associated with this JIRA issue.</p> |
| |
| <p>If the Apache JIRA system is not in use, then override options may be provided on the command line to point to a different JIRA instance.</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--jira-issue-re</span><span class="o">=</span><span class="s1">'^PROJECT-[0-9]+$'</span> <span class="nt">--jira-base-url</span><span class="o">=</span><span class="s1">'https://example.com/jira'</span> PROJECT-90 |
| </code></pre></div> |
| <p>… will process the patch file attached to PROJECT-90 on the JIRA instance located on the example.com server.</p> |
| |
| <h2 id="github">GITHUB</h2> |
| |
| <p><code>test-patch</code> has built-in support for Github via the <code>github</code> plug-in. <code>test-patch</code> supports many forms of providing pull requests to work on:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--github-repo</span><span class="o">=</span>apache/pig GH:99 |
| </code></pre></div> |
| <p>or</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all https://github.com/apache/pig/pulls/99 |
| </code></pre></div> |
| <p>or</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all https://github.com/apache/pig/pulls/99.patch |
| </code></pre></div> |
| <p>… will process PR #99 on the apache/pig repo.</p> |
| |
| <h2 id="gitlab">GITLAB</h2> |
| |
| <p><code>test-patch</code> has support for Gitlab via the <code>gitlab</code> plug-in. <code>test-patch</code> supports many forms of providing merge requests to work on:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--gitlab-repo</span><span class="o">=</span>_a__w_/yetus GL:1 |
| </code></pre></div> |
| <p>or</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all https://gitlab.com/_a__w_/yetus/merge_requests/3 |
| </code></pre></div> |
| <p>or</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all https://gitlab.com/_a__w_/yetus/merge_requests/3.patch |
| </code></pre></div> |
| <p>… will process MR #3 on the _a__w_/yetus repo.</p> |
| |
| <h2 id="generic-urls">Generic URLs</h2> |
| |
| <p>Luckily, <code>test-patch</code> supports ways to provide unified diffs via URLs.</p> |
| |
| <p>For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all https://example.com/webserver/file.patch |
| </code></pre></div> |
| <p>process the file.patch from the example.com webserver.</p> |
| |
| <h1 id="excluding-files">Excluding Files</h1> |
| |
| <p>Some repositories have content that is either imported from other sources (aka "vendored") or in some<br /> |
| other way have files that are known to break tests. By default, <code>.yetus/excludes.txt</code> will be read for any<br /> |
| file, directory, or regular expression as the list to remove from test results. The file to read<br /> |
| may be overwritten by using the <code>--excludes</code> flag:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--excludes</span><span class="o">=(</span>filename<span class="o">)</span> <span class="o">(</span>other options<span class="o">)</span> |
| </code></pre></div> |
| <div class="highlight"><pre class="highlight plaintext"><code>NOTE: Do not confuse file globs for regular expressions. With regular expressions, `a*` will match `aaaaaaaa` |
| but not `ab`. To match all characters any number of times, you need `.*` as your wildcard expression. |
| </code></pre></div> |
| <h1 id="warn-only-test-results">"Warn-only" Test Results</h1> |
| |
| <p>In some cases, test plug-ins may always generate fail results in ways that cannot be avoided or are so<br /> |
| monumental to fix that you just want to keep track of the results without ever failing the run. <code>test-patch</code><br /> |
| provides the <code>--tests-filter</code> option to do just that; print the results but don't fail the job. For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--tests-filter</span><span class="o">=</span>checkstyle,javadoc <span class="o">(</span>other options<span class="o">)</span> |
| </code></pre></div> |
| <p>… will always force the <code>checkstyle</code> and <code>javadoc</code> tests to never vote -1.</p> |
| |
| <h1 id="project-specific-capabilities">Project-specific Capabilities</h1> |
| |
| <p>Due to the extensible nature of the system, <code>test-patch</code> allows for projects to define project-specific rules which we call personalities. (How to build those rules is covered elsewhere.) There are two ways to specify which personality to use:</p> |
| |
| <h2 id="direct-method">Direct Method</h2> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--personality</span><span class="o">=(</span>filename<span class="o">)</span> |
| </code></pre></div> |
| <p>This tells <code>test-patch</code> to use the personality in the given file.</p> |
| |
| <h2 id="project-method">Project Method</h2> |
| |
| <p>However, <code>test-patch</code> can detect if it is a personality that is in its "personality" directory based upon the project name:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--project</span><span class="o">=(</span>project<span class="o">)</span> |
| </code></pre></div> |
| <h1 id="fork-bomb-protection">Fork Bomb Protection</h1> |
| |
| <p>By default, <code>test-patch</code> will set the user soft limit (<code>ulimit -Su</code>) to a relatively low 1,000 processes (and, on some operating systems with some languages such as Java, threads!). This is to prevent errant processes from eating up all system resources. If this limit is too low, it may be necessary to use the <code>--proclimit</code> option. For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--proclimit</span><span class="o">=</span>10000 |
| </code></pre></div> |
| <p>… will set it to be 10,000 processes.</p> |
| |
| <p>NOTE: The actual implementation of this feature is dependent upon the version of Bash. For bash v4 and higher (most operating systems), the fork bomb protection is generally only used for the build and QA tools. This means Apache Yetus should continue to function. For earlier versions of bash (e.g., OS X), the limit is applied to all of test-patch. If the limit is hit, Apache Yetus will itself likely crash.</p> |
| |
| <h1 id="multijdk">MultiJDK</h1> |
| |
| <p>For many projects, it is useful to test Java code against multiple versions of JDKs at the same time. In combination with the <code>java</code> plug-in, <code>test-patch</code> can do this with the <code>--multijdkdirs</code> option:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="nt">--plugins</span><span class="o">=</span>all <span class="nt">--multijdkdirs</span><span class="o">=</span><span class="s2">"/j/d/k/1,/j/d/k/2"</span> |
| </code></pre></div> |
| <p>Not all Java tests support this mode, but those that do will now run their tests with all of the given versions of Java consecutively (e.g., <code>javac</code>–the Java compilation test). Tests that do not support MultiJDK mode (e.g., checkstyle, mvn install) will use JAVA_HOME.</p> |
| |
| <p>NOTE: JAVA_HOME is always appended to the list of JDKs in MultiJDK mode. If JAVA_HOME is in the list, it will be moved to the end.</p> |
| |
| <h1 id="docker">Docker</h1> |
| |
| <p><code>test-patch</code> also has a built-in mode (i.e., no plug-in required) to utilize Docker:</p> |
| |
| <div class="highlight"><pre class="highlight diff"><code><span class="err">$</span> test-patch --docker |
| </code></pre></div> |
| <p>This command will do some preliminary setup and then re-execute itself inside a Docker container. For more information on how to provide a custom Dockerfile and other Docker-specific features, see the specific <a href="../docker">precommit Docker support</a> page and the <a href="../../../../yetus-docker-image">Apache Yetus Docker Hub Images</a> page for more information on the convenience Docker images.</p> |
| |
| <h1 id="upgrading">Upgrading</h1> |
| |
| <p>Currently, Apache Yetus is still undergoing incompatible changes from time to time. Despite that, in many cases<br /> |
| the upgrade process for <code>test-patch</code> and friends is usually just verifying what flags are being passed. To help out,<br /> |
| there is an option to <code>--ignore-unknown-options</code> so that <code>test-patch</code> does not error out if it is given flags it no<br /> |
| longer understands. It will print a list of those unknown options in the end report. In situations where that is<br /> |
| also undesirable, the <code>--report-unknown-options</code> may also be set simultaneously to remove the list from the report.</p> |
| |
| <h1 id="in-closing">In Closing</h1> |
| |
| <p><code>test-patch</code> has many other features and command line options for the basic user. Many of these are self-explanatory. To see the list of options, run <code>test-patch</code> without any options or with <code>--help</code>.</p> |
| |
| </div> |
| |
| <div class="container"> |
| <hr> |
| <footer class="footer"> |
| <div class="row-fluid"> |
| <div class="span12 text-left"> |
| <div class="span12"> |
| Copyright 2008-2023 <a href="https://www.apache.org/">Apache Software Foundation</a>. Licensed under the <a href="https://www.apache.org/licenses/">Apache License v2.0</a>. Apache Yetus and the Apache feather logo are trademarks of The Apache Software Foundation. |
| </div> |
| </div> |
| |
| </div> |
| |
| </footer> |
| </div> |
| |
| </body> |
| </html> |
