| commit | author | age | ||
| 5e3521 | 1 | ## Using Tickets |
| JM | 2 | |
| 5d0f71 | 3 | *SINCE 1.4.0* |
| 5e3521 | 4 | |
| JM | 5 | ### Creating Standard Tickets |
| 6 | ||
| 7 | Standard tickets can be created using the web ui. These ticket types include *Bug*, *Enhancement*, *task*, and *Question*. | |
| 8 | ||
| 9 | ### Creating a Proposal Ticket | |
| 10 | ||
| 5d0f71 | 11 | Proposal tickets are created by pushing a **single commit** to the magic ref. They can not be created from the web ui. |
| 5e3521 | 12 | |
| 5d0f71 | 13 | *Why is there a single commit limitation for creating a Proposal Ticket?* |
| 5e3521 | 14 | |
| 5d0f71 | 15 | 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. |
| JM | 16 | |
| 17 | *Why would I create a proposal ticket?* | |
| 18 | ||
| 19 | 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. | |
| 5e3521 | 20 | |
| JM | 21 | *Who can create a proposal ticket?* |
| 22 | ||
| 23 | Any authenticated user who can clone your repository. | |
| 24 | ||
| bf426b | 25 | git clone https://server/r/repo.git |
| JM | 26 | cd repo |
| 5e3521 | 27 | git checkout -b mytopic |
| JM | 28 | ...add a single commit... |
| 29 | git push origin HEAD:refs/for/new | |
| bf426b | 30 | # read ticket id from server output |
| d69d73 | 31 | git branch -u origin/ticket/{id} |
| 5e3521 | 32 | |
| JM | 33 | ### Creating the first Patchset for an Existing Ticket |
| 34 | ||
| bf426b | 35 | If you have an existing ticket that does **not** yet have a proposed patchset you can push using the ticket branch ref. |
| 5e3521 | 36 | |
| JM | 37 | *Who can create the first patchset for an existing ticket?* |
| 38 | ||
| 39 | Any authenticated user who can clone your repository. | |
| 40 | ||
| bf426b | 41 | git clone https://server/r/repo.git |
| JM | 42 | cd repo |
| 43 | git checkout -b ticket/{id} | |
| 5e3521 | 44 | ...add one or more commits... |
| d69d73 | 45 | git push -u origin ticket/{id} |
| 5e3521 | 46 | |
| JM | 47 | ### Safely adding commits to a Patchset for an Existing Ticket |
| 48 | ||
| 49 | *Who can add commits to an existing patchset?* | |
| 50 | ||
| 2f8b4f | 51 | 1. The ticket author |
| JM | 52 | 2. The initial patchset author |
| 5e3521 | 53 | 3. The person set as *responsible* |
| JM | 54 | 4. Any user with write (RW) permissions to the repository |
| 55 | ||
| 56 | ||
| bf426b | 57 | git fetch && git checkout ticket/{id} |
| JM | 58 | git pull --ff-only |
| 5e3521 | 59 | ...add one or more commits... |
| JM | 60 | git push |
| 61 | ||
| 62 | ### Rewriting a Patchset (amend, rebase, squash) | |
| 63 | ||
| 64 | *Who can rewrite a patchset?* | |
| 65 | ||
| 66 | 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. | |
| 67 | ||
| bf426b | 68 | git fetch && git checkout ticket/{id} |
| JM | 69 | git pull --ff-only |
| 5e3521 | 70 | ...amend, rebase, squash... |
| JM | 71 | git push origin HEAD:refs/for/{id} |
| bf426b | 72 | |
| JM | 73 | OR if you have RW+ permissions, then you can push using *-f* flag. |
| 74 | ||
| 75 | git push -f | |
| 76 | ||
| 77 | ### Updating your copy of a rewritten Patchset | |
| 78 | ||
| 2f8b4f | 79 | 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. |
| bf426b | 80 | |
| JM | 81 | git fetch && git checkout ticket/{id} |
| 82 | git reset --hard origin/ticket/{id} | |
| 83 | ||
| 2f8b4f | 84 | 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. |
| bf426b | 85 | |
| JM | 86 | git branch oldticket ticket/{id} |
| 87 | git fetch && git checkout ticket/{id} | |
| 88 | git reset --hard origin/ticket/{id} | |
| 89 | git cherry-pick <commitid1> <commitid2> | |
| 90 | git branch -D oldticket | |
| 91 | ||
| 2f8b4f | 92 | 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. |
| bf426b | 93 | |
| 5e3521 | 94 | |
| JM | 95 | ### Ticket RefSpecs |
| 96 | ||
| 97 | Gitblit supports two primary push ref specs: the magic ref and the patchset ref. | |
| 98 | ||
| 99 | #### to create a new proposal ticket | |
| 100 | ||
| 101 | | ref | description | | |
| 102 | | :------------------- | :------------------------------------------- | | |
| 103 | | refs/for/new | new proposal for the default branch | | |
| 104 | | refs/for/default | new proposal for the default branch | | |
| 105 | | refs/for/{branch} | new proposal for the specified branch | | |
| 106 | ||
| 107 | #### to add a proposal patchset (first patchset) to an existing ticket | |
| 108 | ||
| 109 | | ref | description | | |
| 110 | | :------------------- | :------------------------------------------- | | |
| 111 | | refs/for/{id} | add new patchset to an existing ticket | | |
| 112 | ||
| 113 | #### to add commits to an existing patchset | |
| 114 | ||
| 115 | | ref | description | | |
| 116 | | :--------------------------- | :----------------------------------- | | |
| 117 | | refs/heads/ticket/{id} | fast-forward an existing patchset | | |
| 118 | ||
| 119 | ||
| 120 | #### to rewrite a patchset (amend, rebase, squash) | |
| 121 | ||
| 122 | | magic ref | description | | |
| 123 | | :------------------- | :------------------------------------------- | | |
| 5d0f71 | 124 | | refs/for/{id} | to rewrite a patchset | |
| 5e3521 | 125 | |
| JM | 126 | ### Ticket RefSpec Tricks |
| 127 | ||
| 128 | Gitblit supports setting some ticket fields from the push refspec. | |
| 129 | ||
| 130 | refs/for/master%topic=bug/42,r=james,m=1.4.1,cc=dave,cc=mark | |
| 131 | ||
| 132 | | parameter | description | | |
| 133 | | :-------- | :-------------------------------------------------------------- | | |
| 134 | | t | assign a *topic* to the ticket (matched against bugtraq config) | | |
| 135 | | r | set the *responsible* user | | |
| 136 | | m | set the *milestone* for patchset integration | | |
| 137 | | cc | add this account to the *watch* list (multiple ccs allowed) | | |
| 138 | ||
| 139 | #### examples | |
| 140 | ||
| 5d0f71 | 141 | 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. |
| 5e3521 | 142 | |
| 5d0f71 | 143 | git push origin HEAD:refs/for/12%cc=james,cc=mark,t=JIRA-123 |
| 5e3521 | 144 | |
| 5d0f71 | 145 | Add some commits (fast-forward) to ticket *12*. Set the milestone to *1.4.1*. |
| 5e3521 | 146 | |
| 5d0f71 | 147 | git push origin HEAD:refs/heads/ticket/12%m=1.4.1 |
| 5e3521 | 148 | |
| JM | 149 | ### Merging Patchsets |
| 150 | ||
| 9bb31c | 151 | The Gitblit web ui offers a merge button which will work for clean merges of a patchset to the integration branch. |
| 5e3521 | 152 | |
| JM | 153 | 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). |
| 154 | ||
| 155 | git pull origin master | |
| 156 | git checkout -b ticket-{id} master | |
| 157 | git pull origin ticket/{id} | |
| 158 | git checkout master | |
| 159 | git merge ticket-{id} | |
| 160 | git push origin master | |
| bf426b | 161 | git branch -d ticket-{id} |
| 5e3521 | 162 | |
| JM | 163 | ### Closing Tickets on Push with a Completely New Patchset |
| 164 | ||
| 165 | 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. | |
| 166 | ||
| 167 | 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). | |
| 168 | ||
| 169 | ### Reopening Tickets with Patchsets | |
| 170 | ||
| 171 | 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. | |
| 172 | ||
| 173 | This allows you to continue the discussion and create a new patchset that hopefully resolves the need. | |
| 174 | ||
| 175 | **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. | |
| 176 | ||
| 177 | ### Reviews | |
| 178 | ||
| 5d0f71 | 179 | Gitblit includes a very simple patchset scoring mechanism. Gitblit is not code-review system, but for those who have simple needs, this may suffice. |
| 5e3521 | 180 | |
| JM | 181 | - +2, approved: patchset can be merged |
| 182 | - +1, looks good: someone else must approve for merge | |
| 183 | - -1, needs improvement: please do not merge | |
| 184 | - -2, vetoed: patchset may not be merged | |
| 185 | ||
| 2f8b4f | 186 | 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. |
| JM | 187 | |
| 188 | #### Reviews and Updated or Rewritten Patchsets | |
| 5e3521 | 189 | |
| 5d0f71 | 190 | 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. |
