gitblit/src/site/tickets_using.mkd

## Using Tickets

*PREVIEW 1.4.0*

### Creating Standard Tickets

Standard tickets can be created using the web ui.  These ticket types include *Bug*, *Enhancement*, *task*, and *Question*.

### Creating a Proposal Ticket

Proposal tickets are created by pushing a patchset to the magic ref.  They can not be created from the web ui.

*Why should I create a proposal ticket?*

Because you are too lazy to create a ticket in the web ui first.  The proposal ticket is a convenience mechanism.  It allows you to propose changes using Git, not your browser.

*Who can create a proposal ticket?*

Any authenticated user who can clone your repository.

    git checkout -b mytopic
    ...add a single commit...
    git push origin HEAD:refs/for/new
    git branch --set-upstream-to={remote}/ticket/{id}

### Creating the first Patchset for an Existing Ticket

If you have an existing ticket that does **not*** yet have a proposed patchset you can push using the magic ref.

*Who can create the first patchset for an existing ticket?*

Any authenticated user who can clone your repository.

    git checkout -b mytopic
    ...add one or more commits...
    git push origin HEAD:refs/for/{id}
    git branch --set-upstream-to={remote}/ticket/{id}

### Safely adding commits to a Patchset for an Existing Ticket

*Who can add commits to an existing patchset?*

1. The author of the ticket
2. The author of the initial patchset
3. The person set as *responsible*
4. Any user with write (RW) permissions to the repository


    git checkout ticket/{id}
    ...add one or more commits...
    git push

### Rewriting a Patchset (amend, rebase, squash)

*Who can rewrite a patchset?*

See the above rules for who can add commits to a patchset. You do **not** need rewind (RW+) to the repository to push a non-fast-forward patchset.  Gitblit will detect the non-fast-forward update and create a new patchset ref.  This preserves the previous patchset.

    git checkout ticket/{id}
    ...amend, rebase, squash...
    git push origin HEAD:refs/for/{id}

### Ticket RefSpecs

Gitblit supports two primary push ref specs: the magic ref and the patchset ref.

#### to create a new proposal ticket

| ref                  | description                                  |
| :------------------- | :------------------------------------------- |
| refs/for/new         | new proposal for the default branch          |
| refs/for/default     | new proposal for the default branch          |
| refs/for/{branch}    | new proposal for the specified branch        |

#### to add a proposal patchset (first patchset) to an existing ticket

| ref                  | description                                  |
| :------------------- | :------------------------------------------- |
| refs/for/{id}        | add new patchset to an existing ticket       |

#### to add commits to an existing patchset

| ref                          | description                          |
| :--------------------------- | :----------------------------------- |
| refs/heads/ticket/{id}       | fast-forward an existing patchset    |


#### to rewrite a patchset (amend, rebase, squash)

| magic ref            | description                                  |
| :------------------- | :------------------------------------------- |
| refs/for/{id}        | add new patchset to an existing ticket       |

### Ticket RefSpec Tricks

Gitblit supports setting some ticket fields from the push refspec.

    refs/for/master%topic=bug/42,r=james,m=1.4.1,cc=dave,cc=mark

| parameter | description                                                     |
| :-------- | :-------------------------------------------------------------- |
| t         | assign a *topic* to the ticket (matched against bugtraq config) |
| r         | set the *responsible* user                                      |
| m         | set the *milestone* for patchset integration                    |
| cc        | add this account to the *watch* list (multiple ccs allowed)     |

#### examples

Create a new patchset for ticket *12*, add *james* and *mark* to the watch list, and set the topic to *issue-123* which will be regex-matched against the repository bugtraq configuration.

    git push origin HEAD:refs/for/12%cc=james,cc=mark,t=issue-123

Add some commits to ticket *123* patchset *5*.  Set the milestone to *1.4.1*.

    git push origin HEAD:refs/heads/ticket/123/5%m=1.4.1

### Merging Patchsets

The Gitblit web ui offers a merge button which *should work* but is not fully tested.  Gitblit does verify that you can cleanly merge a patchset to the integration branch.

There are complicated merge scenarios for which it may be best to merge using your Git client.  There are several ways to do this, here is a safe merge strategy which pulls into a new branch and then fast-forwards your integration branch, assuming you were happy with the pull (merge).

    git pull origin master
    git checkout -b ticket-{id} master
    git pull origin ticket/{id}
    git checkout master
    git merge ticket-{id}
    git push origin master

### Closing Tickets on Push with a Completely New Patchset

Gitblit will look for patchset references on pushes to normal branches.  If it finds a reference (like would be found in the previous merge instructions), the ticket is resolved as merged and everyone is notified.

If you do not need to create a patchset for review, you can just push a commit to the integration branch that contains `fixes #1` or `closes #1` in the commit message.  Gitblit will identify the ticket, create a new patchset with that commit as the tip, and resolve the ticket as merged.  (And if the integration branch is not specified in the ticket - this is the case for a ticket without any existing patchsets - Gitblit will resolve the ticket as merged to the pushed branch).

### Reopening Tickets with Patchsets

Gitblit allows you to reopen a Ticket with a merged patchset.  Since Gitblit allows patchset rewrites and versions patchsets, this seems like a logical capability.  There is no need to create another ticket for a feature request or bug report if the merged commits did not actually resolve the ticket.

This allows you to continue the discussion and create a new patchset that hopefully resolves the need.

**NOTE:**  There is one caveat to this feature.  You can not push patchsets to a closed ticket; Gitblit will reject the push.  You must first reopen the ticket through the web ui before you may push your patchset update or new patchset.

### Reviews

Gitblit includes a very simple review scoring mechanism.

- +2, approved: patchset can be merged
- +1, looks good: someone else must approve for merge
- -1, needs improvement: please do not merge
- -2, vetoed: patchset may not be merged

Only users with write (RW) permissions to the repository can give a +2 and -2 score.  Any other user is free to score +/-1.

If the patchset is updated or rewritten, all reviews are reset; reviews apply to specific revisions of patchsets - they are not blanket approvals/disapprovals.