Merge pull request #1073 from gitblit/1062-DocEditorUpdates

Paul Martin

2016-04-30 a502d96a860456ec5e8c96761db70f7cabb74751

 src/site/tickets_using.mkd

@@ -1,6 +1,6 @@
## Using Tickets

*PREVIEW 1.4.0*
*SINCE 1.4.0*

### Creating Standard Tickets

@@ -8,47 +8,64 @@

### 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.
Proposal tickets are created by pushing a **single commit** to the magic ref.  They can not be created from the web ui.

*Why should I create a proposal ticket?*
*Why is there a single commit limitation for creating 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.
Because the ticket which will be created for your commit will use your commit's message to define the Ticket's *title* and *description*.  After the ticket is created, you can add as many commits as you want to the ticket's branch.

*Why would 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 a change using Git, not your browser.

*Who can create a proposal ticket?*

Any authenticated user who can clone your repository.

    git clone https://server/r/repo.git
    cd repo
    git checkout -b mytopic
    ...add a single commit...
    git push origin HEAD:refs/for/new
    git branch --set-upstream-to={remote}/ticket/{id}
    # read ticket id from server output
    git branch -u origin/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.
If you have an existing ticket that does **not** yet have a proposed patchset you can push using the ticket branch ref.

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

Any authenticated user who can clone your repository.

    git checkout -b mytopic
    git clone https://server/r/repo.git
    cd repo
    git checkout -b ticket/{id}
    ...add one or more commits...
    git push origin HEAD:refs/for/{id}
    git branch --set-upstream-to={remote}/ticket/{id}
    git push -u origin 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
1. The ticket author
2. The initial patchset author
3. The person set as *responsible*
4. Any user with write (RW) permissions to the repository


    git checkout ticket/{id}
    git fetch && git checkout ticket/{id}
    git pull --ff-only
    ...add one or more commits...
    git push

### Checking-Out a Named Branch for an Existing Ticket with a Patchset

If you prefer to name your local ticket branches rather than using the default integer ids, you can do this with a little more syntax.

    git checkout -b my_fix --track origin/ticket/{id}

This will create a local branch named *my_fix* which tracks the upstream ticket branch.

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

@@ -56,9 +73,29 @@

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}
    git fetch && git checkout ticket/{id}
    git pull --ff-only
    ...amend, rebase, squash...
    git push origin HEAD:refs/for/{id}

OR if you have RW+ permissions, then you can push using *-f* flag.

    git push -f

### Updating your copy of a rewritten Patchset

If a patchset has been rewritten you can no longer simply *pull* to update.  Let's assume your checkout **does not** have any unshared commits - i.e. it represents the previous patchset.  The simplest way to update your branch to the current patchset is to reset it using the `-B` checkout flag.

    git fetch && git checkout -B ticket/{id}

If you **do** have unshared commits then you'll could make a new temporary branch and then cherry-pick your changes onto the rewritten patchset.

    git branch oldticket ticket/{id}
    git fetch && git checkout -B ticket/{id}
    git cherry-pick <commitid1> <commitid2>
    git branch -D oldticket

Git is a very flexible tool, there are no doubt several other strategies you could use to resolve this situation.  The above solution is just one way.

### Ticket RefSpecs

@@ -89,7 +126,7 @@

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

### Ticket RefSpec Tricks

@@ -106,17 +143,17 @@

#### 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.
Create a new patchset for ticket *12*, add *james* and *mark* to the watch list, and set the topic to *JIRA-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
    git push origin HEAD:refs/for/12%cc=james,cc=mark,t=JIRA-123

Add some commits to ticket *123* patchset *5*.  Set the milestone to *1.4.1*.
Add some commits (fast-forward) to ticket *12*.  Set the milestone to *1.4.1*.

    git push origin HEAD:refs/heads/ticket/123/5%m=1.4.1
    git push origin HEAD:refs/heads/ticket/12%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.
The Gitblit web ui offers a merge button which will work for clean merges of 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).

@@ -126,6 +163,7 @@
    git checkout master
    git merge ticket-{id}
    git push origin master
    git branch -d ticket-{id}

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

@@ -143,13 +181,15 @@

### Reviews

Gitblit includes a very simple review scoring mechanism.
Gitblit includes a very simple patchset scoring mechanism.  Gitblit is not  code-review system, but for those who have simple needs, this may suffice.

- +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.
Only users with write (RW) permissions to the repository can give a +2 and -2 score.  All other users are allowed to score +/-1.  If the repository is configured to *require approval* then then +2 score has an important meaning.  The merge button will only be shown if there is at least one +2 score and no -2 scores.  If there is a -2 score, the merge is blocked by the web ui.  Users with RW permissions, however, can still manually merge and push the patchset to the integration branch; Gitblit does not enforce vetoed patchsets on push.

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

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