<!---
  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>

<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 &lt;pluginname&gt;
</code></pre></div>
<ul>
  <li>
    <p>pluginname_locate_patch</p>

    <ul>
      <li>Given input from the user, download the patch if possible.</li>
    </ul>
  </li>
  <li>
    <p>pluginname_determine_branch</p>

    <ul>
      <li>Using any heuristics available, return the branch to process, if possible.</li>
    </ul>
  </li>
  <li>
    <p>pluginname_determine_issue</p>

    <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>
    <p>pluginname_write_comment</p>

    <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>
    <p>pluginname_linecomments</p>

    <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>
    <p>pluginname_finalreport</p>

    <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.sh <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 https://bz.apache.org/bugzilla .</p>

<h1 id="github-specific">GitHub Specific</h1>

<p>GitHub supports the full range of functionality, including putting comments on individual lines.  Be aware, however, that test-patch.sh will (generally) require that GitHub PRs be fully rebased (i.e., a single commit) in many circumstances.</p>

<p>By default, the GitHub plug-in assumes that https://github.com is the base URL for GitHub.  Enterprise users may override this with the <code>--github-base-url</code> for the normal web user interface and <code>--github-api-url</code> for the API URL.  Personalities may use GITHUB_API_URL and GITHUB_BASE_URL.</p>

<p>The specific repository on GitHub is defined with either <code>--github-repo</code> on the command line or GITHUB_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 GitHub plug-in supports two types:</p>

<ul>
  <li>
    <p>Token-based:  <code>--github-token</code> or GITHUB_TOKEN</p>
  </li>
  <li>
    <p>Username/password: <code>--github-user</code>/ GITHUB_USER , <code>--github-password</code> / GITHUB_PASSWD</p>
  </li>
</ul>

<p>The default value for  GITHUB_USER is the value of <code>--project</code> suffixed with QA.  For example,<br />
<code>--project=yetus</code> will set <code>GITHUB_USER=yetusqa</code>.</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>

<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 https://issues.apache.org/jira 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>
