Repository: yetus Updated Branches: refs/heads/asf-site 6c06f83a2 -> 2d7ed091d
YETUS-59. Verify any Cat X runtime dependencies are optional Project: http://git-wip-us.apache.org/repos/asf/yetus/repo Commit: http://git-wip-us.apache.org/repos/asf/yetus/commit/2d7ed091 Tree: http://git-wip-us.apache.org/repos/asf/yetus/tree/2d7ed091 Diff: http://git-wip-us.apache.org/repos/asf/yetus/diff/2d7ed091 Branch: refs/heads/asf-site Commit: 2d7ed091d5f028da7407120473130e38d322ddab Parents: 6c06f83 Author: Allen Wittenauer <[email protected]> Authored: Fri Oct 16 10:45:04 2015 -0700 Committer: Allen Wittenauer <[email protected]> Committed: Fri Oct 16 10:45:04 2015 -0700 ---------------------------------------------------------------------- .../latest/precommit-advanced/index.html | 48 ++++++++++++++++---- documentation/latest/precommit-basic/index.html | 29 ++++++++++-- 2 files changed, 64 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/yetus/blob/2d7ed091/documentation/latest/precommit-advanced/index.html ---------------------------------------------------------------------- diff --git a/documentation/latest/precommit-advanced/index.html b/documentation/latest/precommit-advanced/index.html index 6163e21..66619c8 100644 --- a/documentation/latest/precommit-advanced/index.html +++ b/documentation/latest/precommit-advanced/index.html @@ -117,7 +117,7 @@ <ul> <li><a href="#Docker_Support">Docker Support</a></li> <li><a href="#Plug-ins">Plug-ins</a></li> -<li><a href="#Configuring_for_Other_Projects">Configuring for Other Projects</a></li> +<li><a href="#Personalities">Personalities</a></li> <li><a href="#Important_Variables">Important Variables</a></li> </ul> @@ -133,15 +133,15 @@ <h1 id="plug-ins">Plug-ins</h1> -<p>test-patch allows one to add to its basic feature set via plug-ins. There is a directory called test-patch.d off of the directory where test-patch.sh lives. Inside this directory one may place some bash shell fragments that, if setup with proper functions, will allow for test-patch to call it as necessary. Different plug-ins have specific functions for that particular functionality. In this document, the common functions as well as test functions are covered. See other documentat for pertinent information for the other plug-in types.</p> +<p>test-patch allows one to add to its basic feature set via plug-ins. There is a directory called test-patch.d off of the directory where test-patch.sh lives. Inside this directory one may place some bash shell fragments that, if setup with proper functions, will allow for test-patch to call it as necessary. Different plug-ins have specific functions for that particular functionality. In this document, the common functions available to all/most plug-ins are covered. Test plugins are covered below. See other documentation for pertinent information for the other plug-in types.</p> <h2 id="common-plug-in-functions">Common Plug-in Functions</h2> <p>Every plug-in must have one line in order to be recognized, usually an ‘add’ statement. Test plug-ins, for example, have this statement:</p> -<pre class="highlight shell"><code>add_plugin <pluginname> +<pre class="highlight shell"><code>add_test_type <pluginname> </code></pre> -<p>This function call registers the <code>pluginname</code> so that test-patch knows that it exists. The <code>pluginname</code> also acts as the key to the custom functions that you can define. For example:</p> +<p>This function call registers the <code>pluginname</code> so that test-patch knows that it exists. Plug-in names must be unique across all the different plug-in types. Additionally, the 'all’ plug-in is reserved. The <code>pluginname</code> also acts as the key to the custom functions that you can define. For example:</p> <pre class="highlight shell"><code><span class="k">function </span>pluginname_filefilter </code></pre> @@ -194,10 +194,22 @@ </ul></li> </ul> -<h1 id="test-plug-ins">Test Plug-ins</h1> +<h2 id="plug-in-importation">Plug-in Importation</h2> -<p>Plugins geared towards independent tests are registed via:</p> -<pre class="highlight shell"><code>add_plugin <pluginname> +<p>Plug-ins are imported from several key directories:</p> + +<ul> +<li><p>core.d is an internal-to-Yetus directory that first loads the basic Yetus library, followed by the common routines used by all of the precommit shell code. This order is dictated by prefixing the plug-in files with a number. Other files in this directory are loaded in shell collated order.</p></li> +<li><p>personality contains bundled personalities for various projects. These will be imported individually based upon either a project name or if specifically identified with the <code>--personality</code> flag.</p></li> +<li><p>test-patch.d contains all of the optional, bundled plug-ins. These are imported last and in shell collated order.</p></li> +</ul> + +<p>If the <code>--skip-system-plugins</code> flag is passed, then only core.d is imported.</p> + +<h2 id="test-plug-ins">Test Plug-ins</h2> + +<p>Plug-ins geared towards independent tests are registed via:</p> +<pre class="highlight shell"><code>add_test_type <pluginname> </code></pre> <ul> @@ -213,7 +225,9 @@ </ul></li> </ul> -<h1 id="configuring-for-other-projects">Configuring for Other Projects</h1> +<h1 id="personalities">Personalities</h1> + +<h2 id="configuring-for-other-projects">Configuring for Other Projects</h2> <p>It is impossible for any general framework to be predictive about what types of special rules any given project may have, especially when it comes to ordering and Maven profiles. In order to direct test-patch to do the correct action, a project <code>personality</code> should be added that enacts these custom rules.</p> @@ -221,6 +235,16 @@ <p>There can be only <strong>one</strong> of each personality function defined.</p> +<h2 id="global-definitions">Global Definitions</h2> + +<p>Globals for personalities should be defined in the <code>personality_globals</code> function. This function is called <em>after</em> the other plug-ins have been imported. This allows one to configure any settings for plug-ins that have been imported safely:</p> +<pre class="highlight shell"><code>funciton personality_globals +<span class="o">{</span> + <span class="nv">PATCH_BRANCH_DEFAULT</span><span class="o">=</span>master + <span class="nv">GITHUB_REPO</span><span class="o">=</span><span class="s2">"apache/yetus"</span> +<span class="o">}</span> +</code></pre> + <h2 id="test-determination">Test Determination</h2> <p>The <code>personality_file_tests</code> function determines which tests to turn on based upon the file name. It is relatively simple. For example, to turn on a full suite of tests for Java files:</p> @@ -286,6 +310,14 @@ <p>This function will tell test-patch that when the javadoc test is being run, do the documentation build at the base of the source repository and make sure the -DskipTests flag is passed to our build tool.</p> +<h2 id="enabling-plug-ins">Enabling Plug-ins</h2> + +<p>Personalities can set the base list of plug-ins to enable and disable for their project via the <code>personality_plugins</code> function. Just call it with the same pattern as the <code>--plugins</code> command line option:</p> +<pre class="highlight shell"><code>personality_plugins <span class="s2">"all,-checkstyle,-findbugs,-asflicense"</span> +</code></pre> + +<p>This list is used if the user does not provide a list of plug-ins.</p> + <h1 id="important-variables">Important Variables</h1> <p>There are a handful of extremely important system variables that make life easier for personality and plug-in writers. Other variables may be provided by individual plug-ins. Check their development documentation for more information.</p> http://git-wip-us.apache.org/repos/asf/yetus/blob/2d7ed091/documentation/latest/precommit-basic/index.html ---------------------------------------------------------------------- diff --git a/documentation/latest/precommit-basic/index.html b/documentation/latest/precommit-basic/index.html index 2fdda2d..b26b1ab 100644 --- a/documentation/latest/precommit-basic/index.html +++ b/documentation/latest/precommit-basic/index.html @@ -159,8 +159,7 @@ as a whole.</p> <h2 id="optional-requirements">Optional Requirements</h2> -<p>Features are plug-in based. These are activated based upon tool availability, the languages being -tested, etc.</p> +<p>Features are plug-in based and enabled either individually or collectively on the command line. From there, these are activated based upon tool availability, the languages being tested, etc. The external dependencies of plug-ins may have different licensing requirements than Apache Yetus.</p> <p>Bug Systems:</p> @@ -191,16 +190,36 @@ tested, etc.</p> <h1 id="basic-usage">Basic Usage</h1> +<p>The first step for a successful deployment is determining which features/plug-ins to enable:</p> +<pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">test</span>-patch.sh --list-plugins +</code></pre> + +<p>This option will list all of the available plug-ins that are installed in the default location. From this list, the specific plug-ins can be enabled:</p> +<pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">test</span>-patch.sh --plugins<span class="o">=</span><span class="s2">"ant,maven,shellcheck,xml"</span> <other options> +</code></pre> + +<p>As a short-cut, every plug-in may be enabled via the special ‘all’ type:</p> +<pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">test</span>-patch.sh --plugins<span class="o">=</span><span class="s2">"all"</span> <other options> +</code></pre> + +<p><code>--plugins</code> also allows some basic “arithmetic”:</p> +<pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">test</span>-patch.sh --plugins<span class="o">=</span><span class="s2">"all,-checkstyle,-findbugs"</span> <other options> +</code></pre> + +<p>This will enable all plug-ins for potential usage, except for checkstyle and findbugs.</p> + +<p><strong>NOTE: The examples in this section will assume that the necessary <code>--plugins</code> option has been set on the command line as approriate for your particular installation.</strong></p> + <p>This command will execute basic patch testing against a patch file stored in “filename”:</p> <pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">cd</span> <your repo> -<span class="gp">$ </span>dev-support/test-patch.sh --dirty-workspace --project<span class="o">=</span>projectname <filename> +<span class="gp">$ </span><span class="nb">test</span>-patch.sh --dirty-workspace --project<span class="o">=</span>projectname <filename> </code></pre> <p>The <code>--dirty-workspace</code> flag tells test-patch that the repository is not clean and it is ok to continue. By default, unit tests are not run since they may take a significant amount of time.</p> <p>To do turn them on, we need to provide the –run-tests option:</p> <pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">cd</span> <your repo> -<span class="gp">$ </span>dev-support/test-patch.sh --dirty-workspace --run-tests <filename> +<span class="gp">$ </span><span class="nb">test</span>-patch.sh --dirty-workspace --run-tests <filename> </code></pre> <p>This is the same command, but now runs the unit tests.</p> @@ -209,7 +228,7 @@ tested, etc.</p> <pre class="highlight shell"><code><span class="gp">$ </span><span class="nb">cd</span> <workrepo> <span class="gp">$ </span>git diff master > /tmp/patchfile <span class="gp">$ </span><span class="nb">cd</span> ../<testrepo> -<span class="gp">$ </span><workrepo>/dev-support/test-patch.sh --basedir<span class="o">=</span><testrepo> --resetrepo /tmp/patchfile +<span class="gp">$ </span><span class="nb">test</span>-patch.sh --basedir<span class="o">=</span><testrepo> --resetrepo /tmp/patchfile </code></pre> <p>We used two new options here. –basedir sets the location of the repository to use for testing. –resetrepo 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>
