| 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 | ||
| 14353c | 62 | ### Checking-Out a Named Branch for an Existing Ticket with a Patchset |
| JM | 63 | |
| 64 | 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. | |
| 65 | ||
| 66 | git checkout -b my_fix --track origin/ticket/{id} | |
| 67 | ||
| 68 | This will create a local branch named *my_fix* which tracks the upstream ticket branch. | |
| 69 | ||
| 5e3521 | 70 | ### Rewriting a Patchset (amend, rebase, squash) |
| JM | 71 | |
| 72 | *Who can rewrite a patchset?* | |
| 73 | ||
| 74 | 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. | |
| 75 | ||
| bf426b | 76 | git fetch && git checkout ticket/{id} |
| JM | 77 | git pull --ff-only |
| 5e3521 | 78 | ...amend, rebase, squash... |
| JM | 79 | git push origin HEAD:refs/for/{id} |
| bf426b | 80 | |
| JM | 81 | OR if you have RW+ permissions, then you can push using *-f* flag. |
| 82 | ||
| 83 | git push -f | |
| 84 | ||
| 85 | ### Updating your copy of a rewritten Patchset | |
| 86 | ||
| 14353c | 87 | 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. |
| bf426b | 88 | |
| 14353c | 89 | git fetch && git checkout -B ticket/{id} |
| bf426b | 90 | |
| 2f8b4f | 91 | 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 | 92 | |
| JM | 93 | git branch oldticket ticket/{id} |
| 14353c | 94 | git fetch && git checkout -B ticket/{id} |
| bf426b | 95 | git cherry-pick <commitid1> <commitid2> |
| JM | 96 | git branch -D oldticket |
| 97 | ||
| 2f8b4f | 98 | 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. |
| 5e3521 | 99 | |
| JM | 100 | ### Ticket RefSpecs |
| 101 | ||
| 102 | Gitblit supports two primary push ref specs: the magic ref and the patchset ref. | |
| 103 | ||
| 104 | #### to create a new proposal ticket | |
| 105 | ||
| 106 | | ref | description | | |
| 107 | | :------------------- | :------------------------------------------- | | |
| 108 | | refs/for/new | new proposal for the default branch | | |
| 109 | | refs/for/default | new proposal for the default branch | | |
| 110 | | refs/for/{branch} | new proposal for the specified branch | | |
| 111 | ||
| 112 | #### to add a proposal patchset (first patchset) to an existing ticket | |
| 113 | ||
| 114 | | ref | description | | |
| 115 | | :------------------- | :------------------------------------------- | | |
| 116 | | refs/for/{id} | add new patchset to an existing ticket | | |
| 117 | ||
| 118 | #### to add commits to an existing patchset | |
| 119 | ||
| 120 | | ref | description | | |
| 121 | | :--------------------------- | :----------------------------------- | | |
| 122 | | refs/heads/ticket/{id} | fast-forward an existing patchset | | |
| 123 | ||
| 124 | ||
| 125 | #### to rewrite a patchset (amend, rebase, squash) | |
| 126 | ||
| 127 | | magic ref | description | | |
| 128 | | :------------------- | :------------------------------------------- | | |
| 5d0f71 | 129 | | refs/for/{id} | to rewrite a patchset | |
| 5e3521 | 130 | |
| JM | 131 | ### Ticket RefSpec Tricks |
| 132 | ||
| 133 | Gitblit supports setting some ticket fields from the push refspec. | |
| 134 | ||
| 135 | refs/for/master%topic=bug/42,r=james,m=1.4.1,cc=dave,cc=mark | |
| 136 | ||
| 137 | | parameter | description | | |
| 138 | | :-------- | :-------------------------------------------------------------- | | |
| 139 | | t | assign a *topic* to the ticket (matched against bugtraq config) | | |
| 140 | | r | set the *responsible* user | | |
| 141 | | m | set the *milestone* for patchset integration | | |
| 142 | | cc | add this account to the *watch* list (multiple ccs allowed) | | |
| 143 | ||
| 144 | #### examples | |
| 145 | ||
| 5d0f71 | 146 | 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 | 147 | |
| 5d0f71 | 148 | git push origin HEAD:refs/for/12%cc=james,cc=mark,t=JIRA-123 |
| 5e3521 | 149 | |
| 5d0f71 | 150 | Add some commits (fast-forward) to ticket *12*. Set the milestone to *1.4.1*. |
| 5e3521 | 151 | |
| 5d0f71 | 152 | git push origin HEAD:refs/heads/ticket/12%m=1.4.1 |
| 5e3521 | 153 | |
| JM | 154 | ### Merging Patchsets |
| 155 | ||
| 9bb31c | 156 | The Gitblit web ui offers a merge button which will work for clean merges of a patchset to the integration branch. |
| 5e3521 | 157 | |
| JM | 158 | 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). |
| 159 | ||
| 160 | git pull origin master | |
| 161 | git checkout -b ticket-{id} master | |
| 162 | git pull origin ticket/{id} | |
| 163 | git checkout master | |
| 164 | git merge ticket-{id} | |
| 165 | git push origin master | |
| bf426b | 166 | git branch -d ticket-{id} |
| 5e3521 | 167 | |
| JM | 168 | ### Closing Tickets on Push with a Completely New Patchset |
| 169 | ||
| 170 | 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. | |
| 171 | ||
| 172 | 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). | |
| 173 | ||
| 174 | ### Reopening Tickets with Patchsets | |
| 175 | ||
| 176 | 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. | |
| 177 | ||
| 178 | This allows you to continue the discussion and create a new patchset that hopefully resolves the need. | |
| 179 | ||
| 180 | **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. | |
| 181 | ||
| 182 | ### Reviews | |
| 183 | ||
| 5d0f71 | 184 | 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 | 185 | |
| JM | 186 | - +2, approved: patchset can be merged |
| 187 | - +1, looks good: someone else must approve for merge | |
| 188 | - -1, needs improvement: please do not merge | |
| 189 | - -2, vetoed: patchset may not be merged | |
| 190 | ||
| 2f8b4f | 191 | 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 | 192 | |
| 193 | #### Reviews and Updated or Rewritten Patchsets | |
| 5e3521 | 194 | |
| 5d0f71 | 195 | 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. |
