# Bug System Support

- Bugzilla Specific
- GitHub Specific
  - GitHub Authentication
- GitLab Specific
- JIRA Specific

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:

    add_bugsystem <pluginname>

- pluginname_locate_patch
  - Given input from the user, download the patch if possible.
- pluginname_determine_branch
  - Using any heuristics available, return the branch to process, if possible.
- pluginname_determine_issue
  - 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.
- pluginname_write_comment
  - Given text input, write this output to the bug system as a comment. NOTE: It is the bug system's responsibility to format appropriately.
- pluginname_linecomments
  - This function allows for the system to write specific comments on specific lines if the bug system supports code review comments.
- pluginname_finalreport
  - Write the final result table to the bug system.

# Bugzilla Specific

Currently, Bugzilla support is read-only. To use it, the Bug ID must be preferenced with 'BZ:'. For example:

    $ test-patch (other options) BZ:4

… will pull down Bugzilla ID #4.

Using the `--bugzilla-base-url` 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.

# GitHub Specific

GitHub supports a large range of functionality, mostly self-adjusting based upon the
environment it is running in. Supported features include GitHub Enterprise, private
repositories, GitHub Statuses, and GitHub Checks Annotations.

Be aware, however, that `test-patch` will (generally) require
that GitHub PRs be fully squashed and rebased (i.e., a single commit) in many
circumstances, especially renames followed by commits to those renamed files. It will
try to fall back to 'diff' format if 'patch' format does not work, exiting
completely if both fail.

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

The specific repository on GitHub is defined with either `--github-repo` on the
command line, GITHUB_REPO in a personality, or automatically determined by various
robot support mechanisms. It should take the form of "user/repo".

GitHub pull requests may be directly processed on the command line in two ways:

- GH:(PR number)
- GHSHA:(PR SHA1 number)

The GitHub bugsystem plugin will attempt to download the unified diff that the pull request references.
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.

## GitHub Authentication

Some operations depend upon authentication credentials. The GitHub plug-in
supports authentication via token. Authentication is
required for controlling the API query rate, accessing private repositories,
reading private pull requests, updating GitHub Statuses (requires
`repo:status` permissions), writing comments to PRs, and other functionality.

Some robots have built-in support for providing GitHub tokens. See
the appropriate documentation for your particular setup.

### GitHub Token

The token is provided via the `--github-token` option.

# GitLab Specific

GitLab supports the full range of functionality, including putting comments on individual lines. Be aware, however, that `test-patch` will (generally) require that GitLab MRs be fully squashed and rebased (i.e., a single commit) in many circumstances.

By default, the GitLab plug-in assumes that https://gitlab.com is the base URL for GitLab. Enterprise users may override this with the `--gitlab-base-url` for the normal web user interface and `--gitlab-api-url` for the API URL. Personalities may use GITLAB_API_URL and GITLAB_BASE_URL.

The specific repository on GitLab is defined with either `--gitlab-repo` on the command line or GITLAB_REPO in a personality. It should take the form of "user/repo".

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 `--gitlab-token` option or GITLAB_TOKEN environment variable.

GitLab merge requests may be directly processed on the command line in two ways:

- GL:(MR number)
- GLSHA:(MR SHA1 number)

The GitLab bugsystem plugin will attempt to download the unified diff that the merge request references.
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.

# JIRA Specific

JIRA support allows both patch downloads and summary writes. It also supports branch detection-based upon the name of the attached patch file.

JIRA issues are invoked by matching the command line option to a specific regular expression as given by the `--jira-issue-re` 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 `--jira-base-url` option or personalities may define via JIRA_URL.

In order to write information on the issue, JIRA requires username and password authentication using the `--jira-user`/`--jira-password` options or the JIRA_USER and JIRA_PASSWORD variables in a personality.

The default value for JIRA_USER is the value of `--project` suffixed with QA. For example,
`--project=yetus` will set `JIRA_USER=yetusqa`.