| <!--- |
| 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="bug-system-support">Bug System Support</h1> |
| |
| <!-- MarkdownTOC levels="1,2" autolink="true" indent=" " bullets="*" bracket="round" --> |
| |
| <ul> |
| <li><a href="#bugzilla-specific">Bugzilla Specific</a></li> |
| <li><a href="#github-specific">GitHub Specific</a> |
| <ul> |
| <li><a href="#github-authentication">GitHub Authentication</a></li> |
| </ul> |
| </li> |
| <li><a href="#gitlab-specific">GitLab Specific</a></li> |
| <li><a href="#jira-specific">JIRA Specific</a></li> |
| </ul> |
| |
| <!-- /MarkdownTOC --> |
| |
| <p>test-patch has the ability to support multiple bug systems. Bug tools have some extra hooks to fetch patches, line-level reporting, and posting a final report. Every bug system plug-in must have one line in order to be recognized:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code>add_bugsystem <pluginname> |
| </code></pre></div> |
| <ul> |
| <li>pluginname_locate_patch |
| <ul> |
| <li>Given input from the user, download the patch if possible.</li> |
| </ul> |
| </li> |
| <li>pluginname_determine_branch |
| <ul> |
| <li>Using any heuristics available, return the branch to process, if possible.</li> |
| </ul> |
| </li> |
| <li>pluginname_determine_issue |
| <ul> |
| <li>Using any heuristics available, set the issue, bug number, etc, for this bug system, if possible. This is typically used to fill in supplementary information in the final output table.</li> |
| </ul> |
| </li> |
| <li>pluginname_write_comment |
| <ul> |
| <li>Given text input, write this output to the bug system as a comment. NOTE: It is the bug system's responsibility to format appropriately.</li> |
| </ul> |
| </li> |
| <li>pluginname_linecomments |
| <ul> |
| <li>This function allows for the system to write specific comments on specific lines if the bug system supports code review comments.</li> |
| </ul> |
| </li> |
| <li>pluginname_finalreport |
| <ul> |
| <li>Write the final result table to the bug system.</li> |
| </ul> |
| </li> |
| </ul> |
| |
| <h1 id="bugzilla-specific">Bugzilla Specific</h1> |
| |
| <p>Currently, Bugzilla support is read-only. To use it, the Bug ID must be preferenced with 'BZ:'. For example:</p> |
| |
| <div class="highlight"><pre class="highlight shell"><code><span class="nv">$ </span>test-patch <span class="o">(</span>other options<span class="o">)</span> BZ:4 |
| </code></pre></div> |
| <p>… will pull down Bugzilla ID #4.</p> |
| |
| <p>Using the <code>--bugzilla-base-url</code> on the command line or BUGZILLA_BASE_URL in a project's personality will define the location of the Bugzilla instance. By default, it is <a href="https://bz.apache.org/bugzilla">https://bz.apache.org/bugzilla</a>.</p> |
| |
| <h1 id="github-specific">GitHub Specific</h1> |
| |
| <p>GitHub supports a large range of functionality, mostly self-adjusting based upon the<br /> |
| environment it is running in. Supported features include GitHub Enterprise, private<br /> |
| repositories, GitHub Statuses, and GitHub Checks Annotations.</p> |
| |
| <p>Be aware, however, that <code>test-patch</code> will (generally) require<br /> |
| that GitHub PRs be fully squashed and rebased (i.e., a single commit) in many<br /> |
| circumstances, especially renames followed by commits to those renamed files. It will<br /> |
| try to fall back to 'diff' format if 'patch' format does not work, exiting<br /> |
| completely if both fail.</p> |
| |
| <p>By default, the GitHub plug-in assumes that <a href="https://github.com">https://github.com</a> is the base URL<br /> |
| for GitHub and <a href="https://api.github.com">https://api.github.com</a> for base of the GitHub API URL. Enterprise<br /> |
| users may override this with the <code>--github-base-url</code> for the normal web user<br /> |
| interface and <code>--github-api-url</code> for the API URL. Personalities may use<br /> |
| GITHUB_API_URL and GITHUB_BASE_URL.</p> |
| |
| <p>The specific repository on GitHub is defined with either <code>--github-repo</code> on the<br /> |
| command line, GITHUB_REPO in a personality, or automatically determined by various<br /> |
| robot support mechanisms. It should take the form of "user/repo".</p> |
| |
| <p>GitHub pull requests may be directly processed on the command line in two ways:</p> |
| |
| <ul> |
| <li>GH:(PR number)</li> |
| <li>GHSHA:(PR SHA1 number)</li> |
| </ul> |
| |
| <p>The GitHub bugsystem plugin will attempt to download the unified diff that the pull request references.<br /> |
| Pull requests that are made off of a specific branch will switch the test repo to that branch, if permitted. If the pull request references a JIRA issue that matches the given JIRA issue regexp in the Subject, the JIRA plug-in will also be invoked as needed.</p> |
| |
| <h2 id="github-authentication">GitHub Authentication</h2> |
| |
| <p>Some operations depend upon authentication credentials. The GitHub plug-in<br /> |
| supports authentication via token. Authentication is<br /> |
| required for controlling the API query rate, accessing private repositories,<br /> |
| reading private pull requests, updating GitHub Statuses (requires<br /> |
| <code>repo:status</code> permissions), writing comments to PRs, and other functionality.</p> |
| |
| <p>Some <a href="../robots">robots</a> have built-in support for providing GitHub tokens. See<br /> |
| the appropriate documentation for your particular setup.</p> |
| |
| <h3 id="github-token">GitHub Token</h3> |
| |
| <p>The token is provided via the <code>--github-token</code> option.</p> |
| |
| <h1 id="gitlab-specific">GitLab Specific</h1> |
| |
| <p>GitLab supports the full range of functionality, including putting comments on individual lines. Be aware, however, that <code>test-patch</code> will (generally) require that GitLab MRs be fully squashed and rebased (i.e., a single commit) in many circumstances.</p> |
| |
| <p>By default, the GitLab plug-in assumes that <a href="https://gitlab.com">https://gitlab.com</a> is the base URL for GitLab. Enterprise users may override this with the <code>--gitlab-base-url</code> for the normal web user interface and <code>--gitlab-api-url</code> for the API URL. Personalities may use GITLAB_API_URL and GITLAB_BASE_URL.</p> |
| |
| <p>The specific repository on GitLab is defined with either <code>--gitlab-repo</code> on the command line or GITLAB_REPO in a personality. It should take the form of "user/repo".</p> |
| |
| <p>In order to comment on issues or, depending upon the security setup of the repo, authentication credentials. The GitLab plug-in supports tokens via the <code>--gitlab-token</code> option or GITLAB_TOKEN environment variable.</p> |
| |
| <p>GitLab merge requests may be directly processed on the command line in two ways:</p> |
| |
| <ul> |
| <li>GL:(MR number)</li> |
| <li>GLSHA:(MR SHA1 number)</li> |
| </ul> |
| |
| <p>The GitLab bugsystem plugin will attempt to download the unified diff that the merge request references.<br /> |
| Merge requests that are made off of a specific branch will switch the test repo to that branch, if permitted. If the merge request references a JIRA issue that matches the given JIRA issue regexp in the Subject, the JIRA plug-in will also be invoked as needed.</p> |
| |
| <h1 id="jira-specific">JIRA Specific</h1> |
| |
| <p>JIRA support allows both patch downloads and summary writes. It also supports branch detection-based upon the name of the attached patch file.</p> |
| |
| <p>JIRA issues are invoked by matching the command line option to a specific regular expression as given by the <code>--jira-issue-re</code> option or via the JIRA_ISSUE_RE personality variable. By default, the plug-in uses <a href="https://issues.apache.org/jira">https://issues.apache.org/jira</a> as the JIRA instance to use. However that may be overwritten via the <code>--jira-base-url</code> option or personalities may define via JIRA_URL.</p> |
| |
| <p>In order to write information on the issue, JIRA requires username and password authentication using the <code>--jira-user</code>/<code>--jira-password</code> options or the JIRA_USER and JIRA_PASSWORD variables in a personality.</p> |
| |
| <p>The default value for JIRA_USER is the value of <code>--project</code> suffixed with QA. For example,<br /> |
| <code>--project=yetus</code> will set <code>JIRA_USER=yetusqa</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> |
