Ticket tracker with patchset contributions

A basic issue tracker styled as a hybrid of GitHub and BitBucket issues.
You may attach commits to an existing ticket or you can push a single
commit to create a *proposal* ticket.

Tickets keep track of patchsets (one or more commits) and allow patchset
rewriting (rebase, amend, squash) by detecing the non-fast-forward
update and assigning a new patchset number to the new commits.

Ticket tracker
--------------

The ticket tracker stores tickets as an append-only journal of changes.
The journals are deserialized and a ticket is built by applying the
journal entries.  Tickets are indexed using Apache Lucene and all
queries and searches are executed against this Lucene index.

There is one trade-off to this persistence design: user attributions are
non-relational.

What does that mean?  Each journal entry stores the username of the
author.  If the username changes in the user service, the journal entry
will not reflect that change because the values are hard-coded.

Here are a few reasons/justifications for this design choice:

1. commit identifications (author, committer, tagger) are non-relational
2. maintains the KISS principle
3. your favorite text editor can still be your administration tool

Persistence Choices
-------------------

**FileTicketService**: stores journals on the filesystem
**BranchTicketService**: stores journals on an orphan branch
**RedisTicketService**: stores journals in a Redis key-value datastore

It should be relatively straight-forward to develop other backends
(MongoDB, etc) as long as the journal design is preserved.

Pushing Commits
---------------

Each push to a ticket is identified as a patchset revision.  A patchset
revision may add commits to the patchset (fast-forward) OR a patchset
revision may rewrite history (rebase, squash, rebase+squash, or amend).
Patchset authors should not be afraid to polish, revise, and rewrite
their code before merging into the proposed branch.

Gitblit will create one ref for each patchset.  These refs are updated
for fast-forward pushes or created for rewrites.  They are formatted as
`refs/tickets/{shard}/{id}/{patchset}`.  The *shard*  is the last two
digits of the id.  If the id < 10, prefix a 0.  The *shard* is always
two digits long.  The shard's purpose is to ensure Gitblit doesn't
exceed any filesystem directory limits for file creation.

**Creating a Proposal Ticket**

You may create a new change proposal ticket just by pushing a **single
commit** to `refs/for/{branch}` where branch is the proposed integration
branch OR `refs/for/new` or `refs/for/default` which both will use the
default repository branch.

    git push origin HEAD:refs/for/new

**Updating a Patchset**

The safe way to update an existing patchset is to push to the patchset
ref.

    git push origin HEAD:refs/heads/ticket/{id}

This ensures you do not accidentally create a new patchset in the event
that the patchset was updated after you last pulled.

The not-so-safe way to update an existing patchset is to push using the
magic ref.

    git push origin HEAD:refs/for/{id}

This push ref will update an exisitng patchset OR create a new patchset
if the update is non-fast-forward.

**Rebasing, Squashing, Amending**

Gitblit makes rebasing, squashing, and amending patchsets easy.

Normally, pushing a non-fast-forward update would require rewind (RW+)
repository permissions.  Gitblit provides a magic ref which will allow
ticket participants to rewrite a ticket patchset as long as the ticket
is open.

    git push origin HEAD:refs/for/{id}

Pushing changes to this ref allows the patchset authors to rebase,
squash, or amend the patchset commits without requiring client-side use
of the *--force* flag on push AND without requiring RW+ permission to
the repository.  Since each patchset is tracked with a ref it is easy to
recover from accidental non-fast-forward updates.

Features
--------

- Ticket tracker with status changes and responsible assignments
- Patchset revision scoring mechanism
- Update/Rewrite patchset handling
- Close-on-push detection
- Server-side Merge button for simple merges
- Comments with Markdown syntax support
- Rich mail notifications
- Voting
- Mentions
- Watch lists
- Querying
- Searches
- Partial miletones support
- Multiple backend options

1 files changed, 324 insertions, 0 deletions

diff --git a/src/main/java/com/gitblit/git/PatchsetCommand.java b/src/main/java/com/gitblit/git/PatchsetCommand.java
new file mode 100644
index 00000000..21d2ac45
--- /dev/null
+++ b/src/main/java/com/gitblit/git/PatchsetCommand.java
@@ -0,0 +1,324 @@
+/*
+ * Copyright 2013 gitblit.com.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.gitblit.git;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Set;
+import java.util.TreeSet;
+
+import org.eclipse.jgit.lib.ObjectId;
+import org.eclipse.jgit.revwalk.RevCommit;
+import org.eclipse.jgit.transport.ReceiveCommand;
+
+import com.gitblit.Constants;
+import com.gitblit.models.TicketModel;
+import com.gitblit.models.TicketModel.Change;
+import com.gitblit.models.TicketModel.Field;
+import com.gitblit.models.TicketModel.Patchset;
+import com.gitblit.models.TicketModel.PatchsetType;
+import com.gitblit.models.TicketModel.Status;
+import com.gitblit.utils.ArrayUtils;
+import com.gitblit.utils.StringUtils;
+
+/**
+ *
+ * A subclass of ReceiveCommand which constructs a ticket change based on a
+ * patchset and data derived from the push ref.
+ *
+ * @author James Moger
+ *
+ */
+public class PatchsetCommand extends ReceiveCommand {
+
+	public static final String TOPIC = "t=";
+
+	public static final String RESPONSIBLE = "r=";
+
+	public static final String WATCH = "cc=";
+
+	public static final String MILESTONE = "m=";
+
+	protected final Change change;
+
+	protected boolean isNew;
+
+	protected long ticketId;
+
+	public static String getBasePatchsetBranch(long ticketNumber) {
+		StringBuilder sb = new StringBuilder();
+		sb.append(Constants.R_TICKETS_PATCHSETS);
+		long m = ticketNumber % 100L;
+		if (m < 10) {
+			sb.append('0');
+		}
+		sb.append(m);
+		sb.append('/');
+		sb.append(ticketNumber);
+		sb.append('/');
+		return sb.toString();
+	}
+
+	public static String getTicketBranch(long ticketNumber) {
+		return Constants.R_TICKET + ticketNumber;
+	}
+
+	public static String getReviewBranch(long ticketNumber) {
+		return "ticket-" + ticketNumber;
+	}
+
+	public static String getPatchsetBranch(long ticketId, long patchset) {
+		return getBasePatchsetBranch(ticketId) + patchset;
+	}
+
+	public static long getTicketNumber(String ref) {
+		if (ref.startsWith(Constants.R_TICKETS_PATCHSETS)) {
+			// patchset revision
+
+			// strip changes ref
+			String p = ref.substring(Constants.R_TICKETS_PATCHSETS.length());
+			// strip shard id
+			p = p.substring(p.indexOf('/') + 1);
+			// strip revision
+			p = p.substring(0, p.indexOf('/'));
+			// parse ticket number
+			return Long.parseLong(p);
+		} else if (ref.startsWith(Constants.R_TICKET)) {
+			String p = ref.substring(Constants.R_TICKET.length());
+			// parse ticket number
+			return Long.parseLong(p);
+		}
+		return 0L;
+	}
+
+	public PatchsetCommand(String username, Patchset patchset) {
+		super(patchset.isFF() ? ObjectId.fromString(patchset.parent) : ObjectId.zeroId(),
+				ObjectId.fromString(patchset.tip), null);
+		this.change = new Change(username);
+		this.change.patchset = patchset;
+	}
+
+	public PatchsetType getPatchsetType() {
+		return change.patchset.type;
+	}
+
+	public boolean isNewTicket() {
+		return isNew;
+	}
+
+	public long getTicketId() {
+		return ticketId;
+	}
+
+	public Change getChange() {
+		return change;
+	}
+
+	/**
+	 * Creates a "new ticket" change for the proposal.
+	 *
+	 * @param commit
+	 * @param mergeTo
+	 * @param ticketId
+	 * @parem pushRef
+	 */
+	public void newTicket(RevCommit commit, String mergeTo, long ticketId, String pushRef) {
+		this.ticketId = ticketId;
+		isNew = true;
+		change.setField(Field.title, getTitle(commit));
+		change.setField(Field.body, getBody(commit));
+		change.setField(Field.status, Status.New);
+		change.setField(Field.mergeTo, mergeTo);
+		change.setField(Field.type, TicketModel.Type.Proposal);
+
+		Set<String> watchSet = new TreeSet<String>();
+		watchSet.add(change.author);
+
+		// identify parameters passed in the push ref
+		if (!StringUtils.isEmpty(pushRef)) {
+			List<String> watchers = getOptions(pushRef, WATCH);
+			if (!ArrayUtils.isEmpty(watchers)) {
+				for (String cc : watchers) {
+					watchSet.add(cc.toLowerCase());
+				}
+			}
+
+			String milestone = getSingleOption(pushRef, MILESTONE);
+			if (!StringUtils.isEmpty(milestone)) {
+				// user provided milestone
+				change.setField(Field.milestone, milestone);
+			}
+
+			String responsible = getSingleOption(pushRef, RESPONSIBLE);
+			if (!StringUtils.isEmpty(responsible)) {
+				// user provided responsible
+				change.setField(Field.responsible, responsible);
+				watchSet.add(responsible);
+			}
+
+			String topic = getSingleOption(pushRef, TOPIC);
+			if (!StringUtils.isEmpty(topic)) {
+				// user provided topic
+				change.setField(Field.topic, topic);
+			}
+		}
+
+		// set the watchers
+		change.watch(watchSet.toArray(new String[watchSet.size()]));
+	}
+
+	/**
+	 *
+	 * @param commit
+	 * @param mergeTo
+	 * @param ticket
+	 * @param pushRef
+	 */
+	public void updateTicket(RevCommit commit, String mergeTo, TicketModel ticket, String pushRef) {
+
+		this.ticketId = ticket.number;
+
+		if (ticket.isClosed()) {
+			// re-opening a closed ticket
+			change.setField(Field.status, Status.Open);
+		}
+
+		// ticket may or may not already have an integration branch
+		if (StringUtils.isEmpty(ticket.mergeTo) || !ticket.mergeTo.equals(mergeTo)) {
+			change.setField(Field.mergeTo, mergeTo);
+		}
+
+		if (ticket.isProposal() && change.patchset.commits == 1 && change.patchset.type.isRewrite()) {
+
+			// Gerrit-style title and description updates from the commit
+			// message
+			String title = getTitle(commit);
+			String body = getBody(commit);
+
+			if (!ticket.title.equals(title)) {
+				// title changed
+				change.setField(Field.title, title);
+			}
+
+			if (!ticket.body.equals(body)) {
+				// description changed
+				change.setField(Field.body, body);
+			}
+		}
+
+		Set<String> watchSet = new TreeSet<String>();
+		watchSet.add(change.author);
+
+		// update the patchset command metadata
+		if (!StringUtils.isEmpty(pushRef)) {
+			List<String> watchers = getOptions(pushRef, WATCH);
+			if (!ArrayUtils.isEmpty(watchers)) {
+				for (String cc : watchers) {
+					watchSet.add(cc.toLowerCase());
+				}
+			}
+
+			String milestone = getSingleOption(pushRef, MILESTONE);
+			if (!StringUtils.isEmpty(milestone) && !milestone.equals(ticket.milestone)) {
+				// user specified a (different) milestone
+				change.setField(Field.milestone, milestone);
+			}
+
+			String responsible = getSingleOption(pushRef, RESPONSIBLE);
+			if (!StringUtils.isEmpty(responsible) && !responsible.equals(ticket.responsible)) {
+				// user specified a (different) responsible
+				change.setField(Field.responsible, responsible);
+				watchSet.add(responsible);
+			}
+
+			String topic = getSingleOption(pushRef, TOPIC);
+			if (!StringUtils.isEmpty(topic) && !topic.equals(ticket.topic)) {
+				// user specified a (different) topic
+				change.setField(Field.topic, topic);
+			}
+		}
+
+		// update the watchers
+		watchSet.removeAll(ticket.getWatchers());
+		if (!watchSet.isEmpty()) {
+			change.watch(watchSet.toArray(new String[watchSet.size()]));
+		}
+	}
+
+	@Override
+	public String getRefName() {
+		return getPatchsetBranch();
+	}
+
+	public String getPatchsetBranch() {
+		return getBasePatchsetBranch(ticketId) + change.patchset.number;
+	}
+
+	public String getTicketBranch() {
+		return getTicketBranch(ticketId);
+	}
+
+	private String getTitle(RevCommit commit) {
+		String title = commit.getShortMessage();
+		return title;
+	}
+
+	/**
+	 * Returns the body of the commit message
+	 *
+	 * @return
+	 */
+	private String getBody(RevCommit commit) {
+		String body = commit.getFullMessage().substring(commit.getShortMessage().length()).trim();
+		return body;
+	}
+
+	/** Extracts a ticket field from the ref name */
+	private static List<String> getOptions(String refName, String token) {
+		if (refName.indexOf('%') > -1) {
+			List<String> list = new ArrayList<String>();
+			String [] strings = refName.substring(refName.indexOf('%') + 1).split(",");
+			for (String str : strings) {
+				if (str.toLowerCase().startsWith(token)) {
+					String val = str.substring(token.length());
+					list.add(val);
+				}
+			}
+			return list;
+		}
+		return null;
+	}
+
+	/** Extracts a ticket field from the ref name */
+	private static String getSingleOption(String refName, String token) {
+		List<String> list = getOptions(refName, token);
+		if (list != null && list.size() > 0) {
+			return list.get(0);
+		}
+		return null;
+	}
+
+	/** Extracts a ticket field from the ref name */
+	public static String getSingleOption(ReceiveCommand cmd, String token) {
+		return getSingleOption(cmd.getRefName(), token);
+	}
+
+	/** Extracts a ticket field from the ref name */
+	public static List<String> getOptions(ReceiveCommand cmd, String token) {
+		return getOptions(cmd.getRefName(), token);
+	}
+
+}
\ No newline at end of file