[[PageOutline(2-5,Contents,pullout)]]

= Track the status of code repository pull requests

== Description

This plugin allows you to track the status of your code repository [wikipedia:"Pull request" pull requests] (PR). A pull request is a request or proposal to submit code changes into a main code repository. ''Pull'' is standard terminology from version control systems like Git or Mercurial. Basically it is a method of submitting contributions. The contributor has a clone of the main repository, pushes the proposed changes to that clone, then submits a pull request. The pull request contains the information required to merge these changes back to the main repository. Usually this means the URL of the repository and a branch (Git) or bookmark name (Mercurial). See also [comment:2:ticket:12406 here].

A special `<command> PR: [arg]` syntax is introduced to create and control pull requests from ticket comments:

[[Image(PullRequestsExample.png, width=600px, border=2)]]

This plugin also adds a macro that lists the queried pull requests, and it also adds a new admin panel, that lists all pull requests:

[[Image(PullRequestsAdmin.png, width=600px, border=2)]]

=== Create Pull Request

A new pull request is automatically created when a ticket comment contains the command `open PR: <link>`.

Examples:
* `open PR: changeset:123/MyForkedRepositoryName`
* `open PR: log:MyForkedRepositoryName@bookmark_name`
* `open PR: [https://www.example.com/git/branches/123 Branch 123]`

The pull request ''number'' is automatically inserted into the ticket comment.

The trac.ini option `[pullrequests] create_commands` can be changed to allow multiple or different commands that create pull requests in different states. The status of a created pull request is always the same as the command that was used to create it.

=== Change Status of a Pull Request

The status of a pull request is automatically changed when a ticket comment contains the command `<newstatus> PR:<number>`.

Examples:
* `reviewed PR:3`
* `closed PR:7`

The trac.ini option `[pullrequests] update_commands` can be changed to allow different commands that change the pull request statuses. The next status of a pull request is always the same as the command that was used to change status.

=== PRQuery Macro

A new macro allows listing all pull requests by author and / or status.

Examples:
* `[[PRQuery()]]`
* `[[PRQuery(status=reviewed)]]`
* `[[PRQuery(status=!closed)]]`
* `[[PRQuery(status=reviewed, author=joe)]]`
* `[[PRQuery(status=open, author=!joe)]]`

== !Bugs/Feature Requests

Existing bugs and feature requests for PullRequestsPlugin are 
[report:9?COMPONENT=PullRequestsPlugin here].

If you have any issues, create a 
[/newticket?component=PullRequestsPlugin new ticket].

[[TicketQuery(component=PullRequestsPlugin&group=type,format=progress)]]

== Download

Download the zipped source from [export:pullrequestsplugin here].

== Source

You can check out PullRequestsPlugin from [/svn/pullrequestsplugin here] using Subversion, or [source:pullrequestsplugin browse the source] with Trac.

== Installation

General instructions on installing Trac plugins can be found on the [TracPlugins#InstallingaTracplugin TracPlugins] page.

== Recent Changes

[[ChangeLog(pullrequestsplugin, 3)]]

== !Author/Contributors

**Author:** [wiki:lucid] [[BR]]
**Maintainer:** [[Maintainer]] [[BR]]
**Contributors:**