http://git-wip-us.apache.org/repos/asf/yetus/blob/7e0fd8e4/documentation/0.6.0/audience-annotations-apidocs/script.js ---------------------------------------------------------------------- diff --git a/documentation/0.6.0/audience-annotations-apidocs/script.js b/documentation/0.6.0/audience-annotations-apidocs/script.js new file mode 100644 index 0000000..b346356 --- /dev/null +++ b/documentation/0.6.0/audience-annotations-apidocs/script.js @@ -0,0 +1,30 @@ +function show(type) +{ + count = 0; + for (var key in methods) { + var row = document.getElementById(key); + if ((methods[key] & type) != 0) { + row.style.display = ''; + row.className = (count++ % 2) ? rowColor : altColor; + } + else + row.style.display = 'none'; + } + updateTabs(type); +} + +function updateTabs(type) +{ + for (var value in tabs) { + var sNode = document.getElementById(tabs[value][0]); + var spanNode = sNode.firstChild; + if (value == type) { + sNode.className = activeTableTab; + spanNode.innerHTML = tabs[value][1]; + } + else { + sNode.className = tableTab; + spanNode.innerHTML = "<a href=\"javascript:show("+ value + ");\">" + tabs[value][1] + "</a>"; + } + } +}
http://git-wip-us.apache.org/repos/asf/yetus/blob/7e0fd8e4/documentation/0.6.0/audience-annotations-apidocs/stylesheet.css ---------------------------------------------------------------------- diff --git a/documentation/0.6.0/audience-annotations-apidocs/stylesheet.css b/documentation/0.6.0/audience-annotations-apidocs/stylesheet.css new file mode 100644 index 0000000..98055b2 --- /dev/null +++ b/documentation/0.6.0/audience-annotations-apidocs/stylesheet.css @@ -0,0 +1,574 @@ +/* Javadoc style sheet */ +/* +Overall document style +*/ + +@import url('resources/fonts/dejavu.css'); + +body { + background-color:#ffffff; + color:#353833; + font-family:'DejaVu Sans', Arial, Helvetica, sans-serif; + font-size:14px; + margin:0; +} +a:link, a:visited { + text-decoration:none; + color:#4A6782; +} +a:hover, a:focus { + text-decoration:none; + color:#bb7a2a; +} +a:active { + text-decoration:none; + color:#4A6782; +} +a[name] { + color:#353833; +} +a[name]:hover { + text-decoration:none; + color:#353833; +} +pre { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; +} +h1 { + font-size:20px; +} +h2 { + font-size:18px; +} +h3 { + font-size:16px; + font-style:italic; +} +h4 { + font-size:13px; +} +h5 { + font-size:12px; +} +h6 { + font-size:11px; +} +ul { + list-style-type:disc; +} +code, tt { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + padding-top:4px; + margin-top:8px; + line-height:1.4em; +} +dt code { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + padding-top:4px; +} +table tr td dt code { + font-family:'DejaVu Sans Mono', monospace; + font-size:14px; + vertical-align:top; + padding-top:4px; +} +sup { + font-size:8px; +} +/* +Document title and Copyright styles +*/ +.clear { + clear:both; + height:0px; + overflow:hidden; +} +.aboutLanguage { + float:right; + padding:0px 21px; + font-size:11px; + z-index:200; + margin-top:-9px; +} +.legalCopy { + margin-left:.5em; +} +.bar a, .bar a:link, .bar a:visited, .bar a:active { + color:#FFFFFF; + text-decoration:none; +} +.bar a:hover, .bar a:focus { + color:#bb7a2a; +} +.tab { + background-color:#0066FF; + color:#ffffff; + padding:8px; + width:5em; + font-weight:bold; +} +/* +Navigation bar styles +*/ +.bar { + background-color:#4D7A97; + color:#FFFFFF; + padding:.8em .5em .4em .8em; + height:auto;/*height:1.8em;*/ + font-size:11px; + margin:0; +} +.topNav { + background-color:#4D7A97; + color:#FFFFFF; + float:left; + padding:0; + width:100%; + clear:right; + height:2.8em; + padding-top:10px; + overflow:hidden; + font-size:12px; +} +.bottomNav { + margin-top:10px; + background-color:#4D7A97; + color:#FFFFFF; + float:left; + padding:0; + width:100%; + clear:right; + height:2.8em; + padding-top:10px; + overflow:hidden; + font-size:12px; +} +.subNav { + background-color:#dee3e9; + float:left; + width:100%; + overflow:hidden; + font-size:12px; +} +.subNav div { + clear:left; + float:left; + padding:0 0 5px 6px; + text-transform:uppercase; +} +ul.navList, ul.subNavList { + float:left; + margin:0 25px 0 0; + padding:0; +} +ul.navList li{ + list-style:none; + float:left; + padding: 5px 6px; + text-transform:uppercase; +} +ul.subNavList li{ + list-style:none; + float:left; +} +.topNav a:link, .topNav a:active, .topNav a:visited, .bottomNav a:link, .bottomNav a:active, .bottomNav a:visited { + color:#FFFFFF; + text-decoration:none; + text-transform:uppercase; +} +.topNav a:hover, .bottomNav a:hover { + text-decoration:none; + color:#bb7a2a; + text-transform:uppercase; +} +.navBarCell1Rev { + background-color:#F8981D; + color:#253441; + margin: auto 5px; +} +.skipNav { + position:absolute; + top:auto; + left:-9999px; + overflow:hidden; +} +/* +Page header and footer styles +*/ +.header, .footer { + clear:both; + margin:0 20px; + padding:5px 0 0 0; +} +.indexHeader { + margin:10px; + position:relative; +} +.indexHeader span{ + margin-right:15px; +} +.indexHeader h1 { + font-size:13px; +} +.title { + color:#2c4557; + margin:10px 0; +} +.subTitle { + margin:5px 0 0 0; +} +.header ul { + margin:0 0 15px 0; + padding:0; +} +.footer ul { + margin:20px 0 5px 0; +} +.header ul li, .footer ul li { + list-style:none; + font-size:13px; +} +/* +Heading styles +*/ +div.details ul.blockList ul.blockList ul.blockList li.blockList h4, div.details ul.blockList ul.blockList ul.blockListLast li.blockList h4 { + background-color:#dee3e9; + border:1px solid #d0d9e0; + margin:0 0 6px -8px; + padding:7px 5px; +} +ul.blockList ul.blockList ul.blockList li.blockList h3 { + background-color:#dee3e9; + border:1px solid #d0d9e0; + margin:0 0 6px -8px; + padding:7px 5px; +} +ul.blockList ul.blockList li.blockList h3 { + padding:0; + margin:15px 0; +} +ul.blockList li.blockList h2 { + padding:0px 0 20px 0; +} +/* +Page layout container styles +*/ +.contentContainer, .sourceContainer, .classUseContainer, .serializedFormContainer, .constantValuesContainer { + clear:both; + padding:10px 20px; + position:relative; +} +.indexContainer { + margin:10px; + position:relative; + font-size:12px; +} +.indexContainer h2 { + font-size:13px; + padding:0 0 3px 0; +} +.indexContainer ul { + margin:0; + padding:0; +} +.indexContainer ul li { + list-style:none; + padding-top:2px; +} +.contentContainer .description dl dt, .contentContainer .details dl dt, .serializedFormContainer dl dt { + font-size:12px; + font-weight:bold; + margin:10px 0 0 0; + color:#4E4E4E; +} +.contentContainer .description dl dd, .contentContainer .details dl dd, .serializedFormContainer dl dd { + margin:5px 0 10px 0px; + font-size:14px; + font-family:'DejaVu Sans Mono',monospace; +} +.serializedFormContainer dl.nameValue dt { + margin-left:1px; + font-size:1.1em; + display:inline; + font-weight:bold; +} +.serializedFormContainer dl.nameValue dd { + margin:0 0 0 1px; + font-size:1.1em; + display:inline; +} +/* +List styles +*/ +ul.horizontal li { + display:inline; + font-size:0.9em; +} +ul.inheritance { + margin:0; + padding:0; +} +ul.inheritance li { + display:inline; + list-style:none; +} +ul.inheritance li ul.inheritance { + margin-left:15px; + padding-left:15px; + padding-top:1px; +} +ul.blockList, ul.blockListLast { + margin:10px 0 10px 0; + padding:0; +} +ul.blockList li.blockList, ul.blockListLast li.blockList { + list-style:none; + margin-bottom:15px; + line-height:1.4; +} +ul.blockList ul.blockList li.blockList, ul.blockList ul.blockListLast li.blockList { + padding:0px 20px 5px 10px; + border:1px solid #ededed; + background-color:#f8f8f8; +} +ul.blockList ul.blockList ul.blockList li.blockList, ul.blockList ul.blockList ul.blockListLast li.blockList { + padding:0 0 5px 8px; + background-color:#ffffff; + border:none; +} +ul.blockList ul.blockList ul.blockList ul.blockList li.blockList { + margin-left:0; + padding-left:0; + padding-bottom:15px; + border:none; +} +ul.blockList ul.blockList ul.blockList ul.blockList li.blockListLast { + list-style:none; + border-bottom:none; + padding-bottom:0; +} +table tr td dl, table tr td dl dt, table tr td dl dd { + margin-top:0; + margin-bottom:1px; +} +/* +Table styles +*/ +.overviewSummary, .memberSummary, .typeSummary, .useSummary, .constantsSummary, .deprecatedSummary { + width:100%; + border-left:1px solid #EEE; + border-right:1px solid #EEE; + border-bottom:1px solid #EEE; +} +.overviewSummary, .memberSummary { + padding:0px; +} +.overviewSummary caption, .memberSummary caption, .typeSummary caption, +.useSummary caption, .constantsSummary caption, .deprecatedSummary caption { + position:relative; + text-align:left; + background-repeat:no-repeat; + color:#253441; + font-weight:bold; + clear:none; + overflow:hidden; + padding:0px; + padding-top:10px; + padding-left:1px; + margin:0px; + white-space:pre; +} +.overviewSummary caption a:link, .memberSummary caption a:link, .typeSummary caption a:link, +.useSummary caption a:link, .constantsSummary caption a:link, .deprecatedSummary caption a:link, +.overviewSummary caption a:hover, .memberSummary caption a:hover, .typeSummary caption a:hover, +.useSummary caption a:hover, .constantsSummary caption a:hover, .deprecatedSummary caption a:hover, +.overviewSummary caption a:active, .memberSummary caption a:active, .typeSummary caption a:active, +.useSummary caption a:active, .constantsSummary caption a:active, .deprecatedSummary caption a:active, +.overviewSummary caption a:visited, .memberSummary caption a:visited, .typeSummary caption a:visited, +.useSummary caption a:visited, .constantsSummary caption a:visited, .deprecatedSummary caption a:visited { + color:#FFFFFF; +} +.overviewSummary caption span, .memberSummary caption span, .typeSummary caption span, +.useSummary caption span, .constantsSummary caption span, .deprecatedSummary caption span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + padding-bottom:7px; + display:inline-block; + float:left; + background-color:#F8981D; + border: none; + height:16px; +} +.memberSummary caption span.activeTableTab span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + margin-right:3px; + display:inline-block; + float:left; + background-color:#F8981D; + height:16px; +} +.memberSummary caption span.tableTab span { + white-space:nowrap; + padding-top:5px; + padding-left:12px; + padding-right:12px; + margin-right:3px; + display:inline-block; + float:left; + background-color:#4D7A97; + height:16px; +} +.memberSummary caption span.tableTab, .memberSummary caption span.activeTableTab { + padding-top:0px; + padding-left:0px; + padding-right:0px; + background-image:none; + float:none; + display:inline; +} +.overviewSummary .tabEnd, .memberSummary .tabEnd, .typeSummary .tabEnd, +.useSummary .tabEnd, .constantsSummary .tabEnd, .deprecatedSummary .tabEnd { + display:none; + width:5px; + position:relative; + float:left; + background-color:#F8981D; +} +.memberSummary .activeTableTab .tabEnd { + display:none; + width:5px; + margin-right:3px; + position:relative; + float:left; + background-color:#F8981D; +} +.memberSummary .tableTab .tabEnd { + display:none; + width:5px; + margin-right:3px; + position:relative; + background-color:#4D7A97; + float:left; + +} +.overviewSummary td, .memberSummary td, .typeSummary td, +.useSummary td, .constantsSummary td, .deprecatedSummary td { + text-align:left; + padding:0px 0px 12px 10px; +} +th.colOne, th.colFirst, th.colLast, .useSummary th, .constantsSummary th, +td.colOne, td.colFirst, td.colLast, .useSummary td, .constantsSummary td{ + vertical-align:top; + padding-right:0px; + padding-top:8px; + padding-bottom:3px; +} +th.colFirst, th.colLast, th.colOne, .constantsSummary th { + background:#dee3e9; + text-align:left; + padding:8px 3px 3px 7px; +} +td.colFirst, th.colFirst { + white-space:nowrap; + font-size:13px; +} +td.colLast, th.colLast { + font-size:13px; +} +td.colOne, th.colOne { + font-size:13px; +} +.overviewSummary td.colFirst, .overviewSummary th.colFirst, +.useSummary td.colFirst, .useSummary th.colFirst, +.overviewSummary td.colOne, .overviewSummary th.colOne, +.memberSummary td.colFirst, .memberSummary th.colFirst, +.memberSummary td.colOne, .memberSummary th.colOne, +.typeSummary td.colFirst{ + width:25%; + vertical-align:top; +} +td.colOne a:link, td.colOne a:active, td.colOne a:visited, td.colOne a:hover, td.colFirst a:link, td.colFirst a:active, td.colFirst a:visited, td.colFirst a:hover, td.colLast a:link, td.colLast a:active, td.colLast a:visited, td.colLast a:hover, .constantValuesContainer td a:link, .constantValuesContainer td a:active, .constantValuesContainer td a:visited, .constantValuesContainer td a:hover { + font-weight:bold; +} +.tableSubHeadingColor { + background-color:#EEEEFF; +} +.altColor { + background-color:#FFFFFF; +} +.rowColor { + background-color:#EEEEEF; +} +/* +Content styles +*/ +.description pre { + margin-top:0; +} +.deprecatedContent { + margin:0; + padding:10px 0; +} +.docSummary { + padding:0; +} + +ul.blockList ul.blockList ul.blockList li.blockList h3 { + font-style:normal; +} + +div.block { + font-size:14px; + font-family:'DejaVu Serif', Georgia, "Times New Roman", Times, serif; +} + +td.colLast div { + padding-top:0px; +} + + +td.colLast a { + padding-bottom:3px; +} +/* +Formatting effect styles +*/ +.sourceLineNo { + color:green; + padding:0 30px 0 0; +} +h1.hidden { + visibility:hidden; + overflow:hidden; + font-size:10px; +} +.block { + display:block; + margin:3px 10px 2px 0px; + color:#474747; +} +.deprecatedLabel, .descfrmTypeLabel, .memberNameLabel, .memberNameLink, +.overrideSpecifyLabel, .packageHierarchyLabel, .paramLabel, .returnLabel, +.seeLabel, .simpleTagLabel, .throwsLabel, .typeNameLabel, .typeNameLink { + font-weight:bold; +} +.deprecationComment, .emphasizedPhrase, .interfaceName { + font-style:italic; +} + +div.block div.block span.deprecationComment, div.block div.block span.emphasizedPhrase, +div.block div.block span.interfaceName { + font-style:normal; +} + +div.contentContainer ul.blockList li.blockList h2{ + padding-bottom:0px; +} http://git-wip-us.apache.org/repos/asf/yetus/blob/7e0fd8e4/documentation/0.6.0/index.html ---------------------------------------------------------------------- diff --git a/documentation/0.6.0/index.html b/documentation/0.6.0/index.html new file mode 100644 index 0000000..ed3a48c --- /dev/null +++ b/documentation/0.6.0/index.html @@ -0,0 +1,182 @@ +<!--- + 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.4.0/">Docs for v0.4.0</a></li> + <li><a href="/documentation/0.5.0/">Docs for v0.5.0</a></li> + <li><a href="/documentation/0.6.0/">Docs for v0.6.0</a></li> + <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</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="http://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://git-wip-us.apache.org/repos/asf?s=yetus";><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="http://www.apache.org";>Apache Homepage</a> + </li> + <li><a href="http://www.apache.org/licenses/";>Apache License</a> + </li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a> + </li> + <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> + </li> + <li><a href="http://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="yetus-precommit">Yetus Precommit</h1> + +<p>The Yetus Precommit Patch Tester allows projects to codify their patch acceptance criteria and then evaluate incoming contributions prior to review by a committer.</p> + +<ul> +<li>Take a quick look at <a href="precommit-glossary">our glossary of terms</a> to ensure you are familiar with the ASF and Maven jargon we’ll use as terminology specific to this project.</li> +<li>For an overview of Yetus’ philosophy on testing contributions and how evaluation is performed, see our <a href="precommit-architecture">overview</a>.</li> +<li>To get started on your project, including an explanation of what we’ll expect in a runtime environment and what optional utilities we’ll leverage, read through the <a href="precommit-basic">basic usage guide</a>.</li> +<li>Customize how precommit interacts with your project by choosing amongst <a href="precommit-buildtools">build systems</a>, <a href="precommit-bugsystems">bug systems</a> and <a href="precommit-testformats">test formats</a>.</li> +<li>If your project has advanced requirements such as module relationships not expressed in Maven, special profiles, or a need on os-specific prerequisites not managed by Maven then you’ll need to use our <a href="precommit-advanced">advanced usage guide</a>.</li> +</ul> + +<p>For a complete guide to the Precommit API, see <a href="precommit-apidocs/">the generated API documentation</a>.</p> + +<h1 id="yetus-release-doc-maker">Yetus Release Doc Maker</h1> + +<p>The Release Documentation Maker allows projects to generate nicely formated Markdown Changelogs and Release Notes based upon JIRA. You can view that +documenation <a href="releasedocmaker">here</a>.</p> + +<h1 id="yetus-shelldocs">Yetus Shelldocs</h1> + +<p>Shelldocs provides generation of html formatted api documentation based on comments on Bash functions. Currently supports documenting API status (public / private) as well as parameters and return values.</p> + +<p>See the shelldocs cli help for more information on usage.</p> +<pre class="highlight shell"><code><span class="gp">$ </span>./shelldocs/shelldocs.py --help +Usage: shelldocs.py --skipprnorep --output OUTFILE --input INFILE <span class="o">[</span>--input INFILE ...] + +Options: + -h, --help show this <span class="nb">help </span>message and <span class="nb">exit</span> + -o OUTFILE, --output<span class="o">=</span>OUTFILE + file to create + -i INFILE, --input<span class="o">=</span>INFILE + file to <span class="nb">read</span> + --skipprnorep Skip Private & Not Replaceable +</code></pre> +<p>You can mark a file to be ignored by shelldocs by adding <q>SHELLDOC-IGNORE</q> as a comment in its own line.</p> + +<h1 id="yetus-audience-annotations">Yetus Audience Annotations</h1> + +<p>Audience Annotations allows you to use Java Annotations to denote which parts of your Java library is publicly consumable and which parts are reserved for a more restricted use. It also provides doclets and examples for generating javadocs limited by audience. +You can refer the user documentation <a href="interface-classification">here</a> and the javadocs <a href="audience-annotations-apidocs/">here</a>.</p> + + </div> + <div class="container"> + <hr> + <footer class="footer"> + <div class="row-fluid"> + <div class="span12 text-left"> + <div class="span12"> + Copyright 2008-2017 <a href="http://www.apache.org/";>Apache Software Foundation</a>. Licensed under the <a href="http://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> http://git-wip-us.apache.org/repos/asf/yetus/blob/7e0fd8e4/documentation/0.6.0/interface-classification/index.html ---------------------------------------------------------------------- diff --git a/documentation/0.6.0/interface-classification/index.html b/documentation/0.6.0/interface-classification/index.html new file mode 100644 index 0000000..c9247fe --- /dev/null +++ b/documentation/0.6.0/interface-classification/index.html @@ -0,0 +1,344 @@ +<!--- + 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.4.0/">Docs for v0.4.0</a></li> + <li><a href="/documentation/0.5.0/">Docs for v0.5.0</a></li> + <li><a href="/documentation/0.6.0/">Docs for v0.6.0</a></li> + <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</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="http://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://git-wip-us.apache.org/repos/asf?s=yetus";><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="http://www.apache.org";>Apache Homepage</a> + </li> + <li><a href="http://www.apache.org/licenses/";>Apache License</a> + </li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a> + </li> + <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> + </li> + <li><a href="http://www.apache.org/security/";>Security</a> + </li> + </ul> + </li> + </li> + </ul> + </div> + <!--/.nav-collapse --> + </div> +</div> + + <div class="container"> + <!--- + Licensed 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. See accompanying LICENSE file. +--> + +<h1 id="apache-yetus-interface-taxonomy-audience-and-stability-classification">Apache Yetus Interface Taxonomy: Audience and Stability Classification</h1> + +<h2 id="motivation">Motivation</h2> + +<p>The interface taxonomy classification provided by Apache Yetus annotations is for guidance to +developers and users of interfaces. The classification guides a developer to +declare the targeted audience or users of an interface and also its stability.</p> + +<ul> +<li><p>Benefits to the user of an interface: Knows which interfaces to use or not use and their stability.</p></li> +<li><p>Benefits to the developer: to prevent accidental changes of interfaces and +hence accidental impact on users or other components or system. This is +particularly useful in large systems with many developers who may not all have +a shared state/history of the project.</p></li> +</ul> + +<h2 id="interface-classification">Interface Classification</h2> + +<p>Yetus provides the following interface classification, derived from the +<a href="http://web.archive.org/web/20061013114610/http://opensolaris.org/os/community/arc/policies/interface-taxonomy/";>OpenSolaris taxonomy</a> +and, to some extent, from taxonomy used inside Yahoo. +Interfaces have two main attributes: Audience and Stability</p> + +<h3 id="audience">Audience</h3> + +<p>Audience denotes the potential consumers of the interface. While many interfaces +are internal/private to the implementation, others are public/external interfaces +and are meant for wider consumption by applications and/or clients. For example, +POSIX definitions in libc are external, while large parts of the kernel are internal or private interfaces. +Also, some interfaces are targeted towards other specific subsystems.</p> + +<p>Identifying the audience of an interface helps define the impact of breaking +it. For instance, it might be okay to break the compatibility of an interface +whose audience is a small number of specific subsystems. On the other hand, it +is probably not okay to break a protocol interfaces that millions of Internet +users depend on.</p> + +<p>Yetus uses the following kinds of audience in order of increasing/wider visibility:</p> + +<h4 id="private">Private</h4> + +<p>The interface is for internal use within a project(such as Apache Hadoop) +and should not be used by applications or by other projects. It is subject to +change at anytime without notice. Most interfaces of a project are Private (also +referred to as project-private).</p> + +<h4 id="limited-private">Limited-Private</h4> + +<p>The interface is used by a specified set of projects or systems (typically +closely related projects). Other projects or systems should not use the +interface. Changes to the interface will be communicated/ negotiated with the +specified projects. For example, in the Apache Hadoop project, some interfaces are +LimitedPrivate{HDFS, MapReduce} in that they are private to the HDFS and +MapReduce subprojects.</p> + +<h4 id="public">Public</h4> + +<p>The interface is for general use by any application.</p> + +<h3 id="stability">Stability</h3> + +<p>Stability denotes how stable an interface is, as in when incompatible changes to +the interface are allowed. Yetus provides the following levels of stability.</p> + +<h4 id="stable">Stable</h4> + +<p>Can evolve while retaining compatibility for minor release boundaries; in other +words, incompatible changes to APIs marked Stable are generally only allowed +at major releases (i.e. at m.0).</p> + +<h4 id="evolving">Evolving</h4> + +<p>Evolving, but incompatible changes are allowed at minor release (i.e. m .x)</p> + +<h4 id="unstable">Unstable</h4> + +<p>Incompatible changes to Unstable APIs are allowed any time. This usually makes +sense for only private interfaces.</p> + +<p>However one may call this out for a supposedly public interface to highlight +that it should not be used as an interface; for public interfaces, labeling it +as Not-an-interface is probably more appropriate than <q>Unstable</q>.</p> + +<p>Examples of publicly visible interfaces that are unstable +(i.e. not-an-interface): GUI, CLIs whose output format will change</p> + +<h4 id="deprecated">Deprecated</h4> + +<p>APIs that could potentially be removed in the future and should not be used.</p> + +<h2 id="how-are-the-classifications-recorded">How are the Classifications Recorded</h2> + +<p>How should the classification be recorded for the annotated APIs?</p> + +<ul> +<li><p>Each interface or class will have the audience and stability recorded using +annotations in org.apache.yetus.classification package.</p></li> +<li><p>The javadoc generated by the maven target javadoc:javadoc lists only the public API.</p></li> +<li><p>One can derive the audience of java classes and java interfaces by the +audience of the package in which they are contained. Hence it is useful to +declare the audience of each java package as public or private (along with the +private audience variations).</p></li> +</ul> + +<h2 id="faq">FAQ</h2> + +<ul> +<li><p>Why aren’t the java scopes (private, package private and public) good enough?</p> + +<ul> +<li>Java’s scoping is not very complete. One is often forced to make a class +public in order for other internal components to use it. It does not have +friends or sub-package-private like C++.</li> +</ul></li> +<li><p>But I can easily access a private implementation interface if it is Java public. +Where is the protection and control?</p> + +<ul> +<li>The purpose of this is not providing absolute access control. Its purpose +is to communicate to users and developers. One can access private +implementation functions in libc; however if they change the internal +implementation details, your application will break and you will have +little sympathy from the folks who are supplying libc. If you use a +non-public interface you understand the risks.</li> +</ul></li> +<li><p>Why bother declaring the stability of a private interface? +Aren’t private interfaces always unstable?</p> + +<ul> +<li>Private interfaces are not always unstable. In the cases where they are +stable they capture internal properties of the system and can communicate +these properties to its internal users and to developers of the interface. + +<ul> +<li>e.g. In HDFS, NN-DN protocol is private but stable and can help +implement rolling upgrades. It communicates that this interface should +not be changed in incompatible ways even though it is private.</li> +<li>e.g. In HDFS, FSImage stability can help provide more flexible roll backs.</li> +</ul></li> +</ul></li> +<li><p>What is the harm in applications using a private interface that is stable? How +is it different than a public stable interface?</p> + +<ul> +<li>While a private interface marked as stable is targeted to change only at +major releases, it may break at other times if the providers of that +interface are willing to changes the internal users of that +interface. Further, a public stable interface is less likely to break even +at major releases (even though it is allowed to break compatibility) +because the impact of the change is larger. If you use a private interface +(regardless of its stability) you run the risk of incompatibility.</li> +</ul></li> +<li><p>Why bother with Limited-private? Isn’t it giving special treatment to some projects? +That is not fair.</p> + +<ul> +<li>First, most interfaces should be public or private; actually let us state +it even stronger: make it private unless you really want to expose it to +public for general use.</li> +<li>Limited-private is for interfaces that are not intended for general +use. They are exposed to related projects that need special hooks. Such a +classification has a cost to both the supplier and consumer of the limited +interface. Both will have to work together if ever there is a need to +break the interface in the future; for example the supplier and the +consumers will have to work together to get coordinated releases of their +respective projects. This should not be taken lightly - if you can get +away with private then do so; if the interface is really for general use +for all applications then you should consider making it public. But remember +that making an interface public has huge responsibility. Sometimes +Limited-private is just right.</li> +<li>A good example of a limited-private interface is BlockLocations in the Apache +Hadoop Project, This is fairly low-level interface that they are willing to +expose to MR and perhaps HBase. They are likely to change it down the road +and at that time they will have to get a coordinated effort with the MR +team to release matching releases. While MR and HDFS are always released +in sync today, they may change down the road.</li> +<li>If you have a limited-private interface with many projects listed then you +are fooling yourself. It is practically public.</li> +<li>It might be worth declaring a special audience classification called +{YourProjectName}-Private for your closely related projects.</li> +</ul></li> +<li><p>Can’t a private interface be treated as project-private also? For example what is +the harm in projects in the Apache Hadoop extended ecosystem, having access to +private classes?</p> + +<ul> +<li>Do we want MR accessing class files that are implementation details inside +HDFS? There used to be many such layer violations in the Apache Hadoop +project that they have been cleaning up over the last few years. It is highly +undesirable for such layer violations to creep back in by no separation +between the major components like HDFS and MR.</li> +</ul></li> +<li><p>Aren’t all public interfaces stable?</p> + +<ul> +<li>One may mark a public interface as evolving in its early days. Here one is +promising to make an effort to make compatible changes but may need to +break it at minor releases.</li> +<li>One example of a public interface that is unstable is where one is +providing an implementation of a standards-body based interface that is +still under development. For example, many companies, in an attempt to be +first to market, have provided implementations of a new NFS protocol even +when the protocol was not fully completed by IETF. The implementor cannot +evolve the interface in a fashion that causes least disruption because +the stability is controlled by the standards body. Hence it is appropriate +to label the interface as unstable.</li> +</ul></li> +</ul> + + </div> + <div class="container"> + <hr> + <footer class="footer"> + <div class="row-fluid"> + <div class="span12 text-left"> + <div class="span12"> + Copyright 2008-2017 <a href="http://www.apache.org/";>Apache Software Foundation</a>. Licensed under the <a href="http://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> http://git-wip-us.apache.org/repos/asf/yetus/blob/7e0fd8e4/documentation/0.6.0/precommit-advanced/index.html ---------------------------------------------------------------------- diff --git a/documentation/0.6.0/precommit-advanced/index.html b/documentation/0.6.0/precommit-advanced/index.html new file mode 100644 index 0000000..b44186f --- /dev/null +++ b/documentation/0.6.0/precommit-advanced/index.html @@ -0,0 +1,405 @@ +<!--- + 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.4.0/">Docs for v0.4.0</a></li> + <li><a href="/documentation/0.5.0/">Docs for v0.5.0</a></li> + <li><a href="/documentation/0.6.0/">Docs for v0.6.0</a></li> + <li><a href="/documentation/in-progress/">In Progress Docs for Contributors</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="http://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://git-wip-us.apache.org/repos/asf?s=yetus";><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="http://www.apache.org";>Apache Homepage</a> + </li> + <li><a href="http://www.apache.org/licenses/";>Apache License</a> + </li> + <li><a href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a> + </li> + <li><a href="http://www.apache.org/foundation/thanks.html";>Thanks</a> + </li> + <li><a href="http://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="test-patch">test-patch</h1> + +<ul> +<li><a href="#docker-support">Docker Support</a></li> +<li><a href="#plug-ins">Plug-ins</a></li> +<li><a href="#personalities">Personalities</a></li> +<li><a href="#important-variables">Important Variables</a></li> +</ul> + +<h1 id="docker-support">Docker Support</h1> + +<p>By default, test-patch runs in the same shell where it was launched. It can alternatively use Docker to launch itself in a container. This is particularly useful if running under a QA environment that does not provide all the necessary binaries. For example, if the patch requires a newer version of Java than what is installed on a Jenkins instance.</p> + +<p>The <code>--docker</code> parameter tells test-patch to run in Docker mode. The <code>--dockerfile</code> parameter allows one to provide a custom Dockerfile. The Dockerfile should contain all of the necessary binaries and tooling needed to run the test. test-patch will copy this file up until the text <q>YETUS CUT HERE</q> to a different directory and then append its necessary hooks to re-launch itself prior to executing docker.</p> + +<p>If a custom Dockerfile cannot be used or the docker executable does not work, test-patch will attempt to recover by switching to its bundled Dockerfile or disabling docker support and running locally. This behavior can be changed with the <code>--dockeronfail</code> option. It takes a list of comma-delimited settings:</p> + +<ul> +<li>fallback - Use the bundled Dockerfile</li> +<li>continue - Turn off docker support</li> +<li>fail - fail the test</li> +</ul> + +<p>The ‘fail’ setting is always the last option that test-patch will use and may be omitted unless it is the only option.</p> + +<p>For example, <code>--dockeronfail=continue</code> means if the Dockerfile can’t be found, just turn off Docker support and continue running. <code>--dockeronfail=fallback</code> will switch to the bundled Dockerfile and then fail the build if docker fails to work. <code>--dockeronfail=fail</code> means to just fail the build and do not try any other mechanisms of recovery. The default is ‘fallback,continue,fail’ which will allow test-patch to try to continue executing as much as it possibily can.</p> + +<p>Be aware that if the Dockerfile is found and the docker command works, test-patch will always fail the build if the Dockerfile itself fails the build. It will not attempt to continue in the non-Docker mode.</p> + +<p>NOTE: If you are using Boot2Docker, you must use directories under /Users (OSX) or C:\Users (Windows) as the base and patchprocess directories (specified by the –basedir and –patch-dir options respectively), because automatically mountable directories are limited to them. See <a href="https://docs.docker.com/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume";>the Docker documentation</a>.</p> + +<p>Dockerfile images will be named with a test-patch prefix and suffix with either a date or a git commit hash. By using this information, test-patch will automatically manage broken/stale container images that are hanging around if it is run in –robot mode. In this way, if Docker fails to build the image, the disk space should eventually be cleaned and returned back to the system. The docker mode can also be run in a <q>safe</q> mode that prevents deletions via the <code>--dockerdelrep</code> option. Specifying this option will cause test-patch to only report what it would have deleted, but not actually remove anything.</p> + +<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 inside 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_test_type <pluginname> +</code></pre> +<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> +<p>defines the filefilter for the <code>pluginname</code> plug-in.</p> + +<p>Similarly, there are other functions that may be defined during the test-patch run:</p> +<pre class="highlight plaintext"><code>HINT: It is recommended to make the pluginname relatively small, 10 characters at the most. Otherwise, the ASCII output table may be skewed. +</code></pre> +<ul> +<li><p>pluginname_usage</p> + +<ul> +<li>executed when the help message is displayed. This is used to display the plug-in specific options for the user.</li> +</ul></li> +<li><p>pluginname_parse_args</p> + +<ul> +<li>executed prior to any other above functions except for pluginname_usage. This is useful for parsing the arguments passed from the user and setting up the execution environment.</li> +</ul></li> +<li><p>pluginname_initialize</p> + +<ul> +<li>After argument parsing and prior to any other work, the initialize step allows a plug-in to do any precursor work, set internal defaults, etc.</li> +</ul></li> +<li><p>pluginname_docker_support</p> + +<ul> +<li>Perform any necessary setup to configure Docker support for the given plugin. Typically this means adding parameters to the docker run command line via adding to the DOCKER_EXTRAARGS array.</li> +</ul></li> +<li><p>pluginname_precheck</p> + +<ul> +<li>executed prior to the patch being applied but after the git repository is setup. Returning a fail status here will exit test-patch.</li> +</ul></li> +<li><p>pluginname_patchfile</p> + +<ul> +<li>executed prior to the patch being applied but after the git repository is setup. This step is intended to perform tests on the content of the patch itself.</li> +</ul></li> +<li><p>pluginname_precompile</p> + +<ul> +<li>executed prior to the compilation part of the lifecycle. This is useful for doing setup work required by the compilation process.</li> +</ul></li> +<li><p>pluginname_postcompile</p> + +<ul> +<li>This step happens after the compile phase.</li> +</ul></li> +<li><p>pluginname_rebuild</p> + +<ul> +<li>Any non-unit tests that require the source to be rebuilt in a destructive way should be run here.</li> +</ul></li> +</ul> + +<h2 id="plug-in-importation">Plug-in Importation</h2> + +<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 Apache 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 registered via:</p> +<pre class="highlight shell"><code>add_test_type <pluginname> +</code></pre> +<ul> +<li><p>pluginname_filefilter</p> + +<ul> +<li>executed while determining which files trigger which tests. This function should use <code>add_test pluginname</code> to add the plug-in to the test list.</li> +</ul></li> +<li><p>pluginname_compile</p> + +<ul> +<li>executed immediately after the actual compilation. This step is intended to be used to verify the results and add extra checking of the compile phase and it’s stdout/stderr.</li> +</ul></li> +<li><p>pluginname_tests</p> + +<ul> +<li>executed after the unit tests have completed.</li> +</ul></li> +<li><p>pluginname_clean</p> + +<ul> +<li>executed to allow the plugin to remove all files that have been generate by this plugin.</li> +</ul></li> +<li><p>pluginname_logfilter</p> + +<ul> +<li>This functions should filter all lines relevant to this test from the logfile. It is called in preparation for the <code>calcdiffs</code> function.</li> +</ul></li> +<li><p>pluginname_calcdiffs</p> + +<ul> +<li>This allows for custom log file difference calculation used to determine the before and after views. The default is to use the last column of a colon delimited line of output and perform a diff. If the plug-in does not provide enough context, this may result in error skew. For example, if three lines in a row have <q>Missing period.</q> as the error, test-patch will not be able to determine exactly which line caused the error. Plug-ins that have this issue will want to use this or potentially modify the normal tool’s output (e.g., checkstyle) to provide a more accurate way to determine differences.</li> +</ul></li> +</ul> + +<p>NOTE: If the plug-in has support for maven, the maven_add_install <code>pluginname</code> should be executed. See more information in Custom Maven Tests in the build tool documentation.</p> + +<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> + +<p>A personality consists of two functions. One that determines which test types to run and another that allows a project to dictate ordering rules, flags, and profiles on a per-module, per-test run.</p> + +<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><span class="k">function </span>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> +<p>Additionally, a personality may require some outside help from the user. The <code>personality_parse_args</code> +function is called almost immediately after the personality is loaded and plug-ins parse arguments.</p> +<pre class="highlight shell"><code><span class="k">function </span>personality_parse_args +<span class="o">{</span> + <span class="nb">echo</span> <span class="s2">"</span><span class="nv">$*</span><span class="s2">"</span> +<span class="o">}</span> +</code></pre> +<p>It is important to note that this function is called AFTER personality_globals.</p> + +<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> +<pre class="highlight shell"><code><span class="k">function </span>personality_file_tests +<span class="o">{</span> + <span class="nb">local </span><span class="nv">filename</span><span class="o">=</span><span class="nv">$1</span> + + <span class="k">if</span> <span class="o">[[</span> <span class="k">${</span><span class="nv">filename</span><span class="k">}</span> <span class="o">=</span>~ <span class="se">\.</span>java<span class="nv">$ </span><span class="o">]]</span>; <span class="k">then + </span>add_test findbugs + add_test javac + add_test javadoc + add_test mvninstall + add_test unit + <span class="k">fi</span> + +<span class="o">}</span> +</code></pre> +<p>The <code>add_test</code> function is used to activate the standard tests. Additional plug-ins (such as checkstyle), will get queried on their own.</p> + +<h2 id="module-profile-determination">Module & Profile Determination</h2> + +<p>Once the tests are determined, it is now time to pick which <a href="precommit-glossary.md#genericoutside-definitions">modules</a> should get used. That’s the job of the <code>personality_modules</code> function.</p> +<pre class="highlight shell"><code><span class="k">function </span>personality_modules +<span class="o">{</span> + + clear_personality_queue + +... + + personality_enqueue_module <module> <flags> + +<span class="o">}</span> +</code></pre> +<p>It takes exactly two parameters <code>repostatus</code> and <code>testtype</code>.</p> + +<p>The <code>repostatus</code> parameter tells the <code>personality</code> function exactly what state the source repository is in. It can only be in one of two states: <code>branch</code> or <code>patch</code>. <code>branch</code> means the patch has not been applied. The <code>patch</code> state is after the patch has been applied.</p> + +<p>The <code>testtype</code> state tells the personality exactly which test is about to be executed.</p> + +<p>In order to communicate back to test-patch, there are two functions for the personality to use.</p> + +<p>The first is <code>clear_personality_queue</code>. This removes the previous test’s configuration so that a new module queue may be built. Custom <code>personality_modules</code> will almost always want to do this as the first action.</p> + +<p>The second is <code>personality_enqueue_module</code>. This function takes two parameters. The first parameter is the name of the module to add to this test’s queue. The second parameter is an option list of additional flags to pass to Maven when processing it. <code>personality_enqueue_module</code> may be called as many times as necessary for your project.</p> +<pre class="highlight plaintext"><code>NOTE: A module name of . signifies the root of the repository. +</code></pre> +<p>For example, let’s say your project uses a special configuration to skip unit tests (-DskipTests). Running unit tests during a javadoc build isn’t very useful and wastes a lot of time. We can write a simple personality check to disable the unit tests:</p> +<pre class="highlight shell"><code><span class="k">function </span>personality_modules +<span class="o">{</span> + <span class="nb">local </span><span class="nv">repostatus</span><span class="o">=</span><span class="nv">$1</span> + <span class="nb">local </span><span class="nv">testtype</span><span class="o">=</span><span class="nv">$2</span> + + <span class="k">if</span> <span class="o">[[</span> <span class="k">${</span><span class="nv">testtype</span><span class="k">}</span> <span class="o">==</span> <span class="s1">'javadoc'</span> <span class="o">]]</span>; <span class="k">then + </span>personality_enqueue_module . -DskipTests + <span class="k">return + fi</span> + ... + +</code></pre> +<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> + +<ul> +<li><p>BUILD_NATIVE will be set to true if the system has requested that non-JVM-based code be built (e.g., JNI or other compiled C code). Under Jenkins, this is always true.</p></li> +<li><p>BUILDTOOL specifies which tool is currently being used to drive compilation. Additionally, many build tools define xyz_ARGS to pass on to the build tool command line. (e.g., MAVEN_ARGS if maven is in use). Projects may set this in their personality. NOTE: today, only one build tool at a time is supported. This may change in the future.</p></li> +<li><p>CHANGED_FILES[@] is an array of all files that appear to be added, deleted, or modified in the patch.</p></li> +<li><p>CHANGED_MODULES[@] is an array of all modules that house all of the CHANGED_FILES[@]. Be aware that the root of the source tree is reported as ‘.’.</p></li> +<li><p>DOCKER_EXTRAARGS[@] is an array of command line arguments to apply to the <code>docker run</code> command.</p></li> +<li><p>GITHUB_REPO is to help test-patch when talking to Github. If test-patch is given just a number on the command line, it will default to using this repo to determine the pull request.</p></li> +<li><p>JIRA_ISSUE_RE is to help test-patch when talking to JIRA. It helps determine if the given project is appropriate for the given JIRA issue.</p></li> +<li><p>MODULE and other MODULE_* are arrays that contain which modules, the status, etc, to be operated upon. These should be treated as read-only by plug-ins.</p></li> +<li><p>PATCH_BRANCH_DEFAULT is the name of the branch in the git repo that is considered the master. This is useful to set in personalities.</p></li> +<li><p>PATCH_DIR is the name of the temporary directory that houses test-patch artifacts (such as logs and the patch file itself)</p></li> +<li><p>PATCH_NAMING_RULE should be a URL that points to a project’s on-boarding documentation for new users. It is used to suggest a review of patch naming guidelines. Since this should be project specific information, it is useful to set in a project’s personality.</p></li> +<li><p>TEST_PARALLEL if parallel unit tests have been requested. Project personalities are responsible for actually enabling or ignoring the request. TEST_THREADS is the number of threads that have been requested to run in parallel.</p></li> +</ul> + + </div> + <div class="container"> + <hr> + <footer class="footer"> + <div class="row-fluid"> + <div class="span12 text-left"> + <div class="span12"> + Copyright 2008-2017 <a href="http://www.apache.org/";>Apache Software Foundation</a>. Licensed under the <a href="http://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>
