From 11eb4b51accebf8a163e8f46f99b067eda80f7b9 Mon Sep 17 00:00:00 2001
From: James Moger <james.moger@gitblit.com>
Date: Fri, 23 May 2014 08:29:14 -0400
Subject: [PATCH] Remove GitBlit static singleton reference from localclone.groovy
---
src/site/tickets_using.mkd | 77 ++++++++++++++++++++++++++++----------
1 files changed, 56 insertions(+), 21 deletions(-)
diff --git a/src/site/tickets_using.mkd b/src/site/tickets_using.mkd
index 71a4ebe..7d9e569 100644
--- a/src/site/tickets_using.mkd
+++ b/src/site/tickets_using.mkd
@@ -1,6 +1,6 @@
## Using Tickets
-*PREVIEW 1.4.0*
+*SINCE 1.4.0*
### Creating Standard Tickets
@@ -8,45 +8,54 @@
### 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 --set-upstream-to=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 --set-upstream 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
@@ -56,9 +65,32 @@
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.
+
+ git fetch && git checkout ticket/{id}
+ git reset --hard origin/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 ticket/{id}
+ git reset --hard origin/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 +121,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,13 +138,13 @@
#### 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
@@ -126,6 +158,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 +176,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.
--
Gitblit v1.9.1