yetus-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From a.@apache.org
Subject yetus git commit: YETUS-59. Verify any Cat X runtime dependencies are optional
Date Fri, 16 Oct 2015 17:45:11 GMT
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 <aw@apache.org>
Authored: Fri Oct 16 10:45:04 2015 -0700
Committer: Allen Wittenauer <aw@apache.org>
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 &lsquo;add&rsquo;
statement.  Test plug-ins, for example, have this statement:</p>
-<pre class="highlight shell"><code>add_plugin &lt;pluginname&gt;
+<pre class="highlight shell"><code>add_test_type &lt;pluginname&gt;
 </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 &#39;all&rsquo; 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 &lt;pluginname&gt;
+<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 &lt;pluginname&gt;
 </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> &lt;other options&gt;
+</code></pre>
+
+<p>As a short-cut, every plug-in may be enabled via the special &lsquo;all&rsquo;
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> &lt;other options&gt;
+</code></pre>
+
+<p><code>--plugins</code> also allows some basic &ldquo;arithmetic&rdquo;:</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> &lt;other options&gt;
+</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 &ldquo;filename&rdquo;:</p>
 <pre class="highlight shell"><code><span class="gp">$ </span><span
class="nb">cd</span> &lt;your repo&gt;
-<span class="gp">$ </span>dev-support/test-patch.sh --dirty-workspace --project<span
class="o">=</span>projectname &lt;filename&gt;
+<span class="gp">$ </span><span class="nb">test</span>-patch.sh --dirty-workspace
--project<span class="o">=</span>projectname &lt;filename&gt;
 </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 &ndash;run-tests option:</p>
 <pre class="highlight shell"><code><span class="gp">$ </span><span
class="nb">cd</span> &lt;your repo&gt;
-<span class="gp">$ </span>dev-support/test-patch.sh --dirty-workspace --run-tests
&lt;filename&gt;
+<span class="gp">$ </span><span class="nb">test</span>-patch.sh --dirty-workspace
--run-tests &lt;filename&gt;
 </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> &lt;workrepo&gt;
 <span class="gp">$ </span>git diff master &gt; /tmp/patchfile
 <span class="gp">$ </span><span class="nb">cd</span> ../&lt;testrepo&gt;
-<span class="gp">$ </span>&lt;workrepo&gt;/dev-support/test-patch.sh
--basedir<span class="o">=</span>&lt;testrepo&gt; --resetrepo /tmp/patchfile
+<span class="gp">$ </span><span class="nb">test</span>-patch.sh --basedir<span
class="o">=</span>&lt;testrepo&gt; --resetrepo /tmp/patchfile
 </code></pre>
 
 <p>We used two new options here.  &ndash;basedir sets the location of the repository
to use for testing.  &ndash;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>


Mime
View raw message