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, 119 insertions, 0 deletions

diff --git a/src/site/tickets_setup.mkd b/src/site/tickets_setup.mkd
new file mode 100644
index 00000000..b1fa7758
--- /dev/null
+++ b/src/site/tickets_setup.mkd
@@ -0,0 +1,119 @@
+## Setting up Tickets
+
+*PREVIEW 1.4.0*
+
+By default, Gitblit is not configured for Tickets.  There are several reasons for this, but the most important one is that you must choose the persistence backend that works best for you.
+
+### tickets.service
+
+*RESTART REQUIRED*
+
+The hardest part of setting up Gitblit Tickets is deciding which backend to use.  Three implementations are provided, each with different strengths and weaknesses.
+
+#### File Ticket Service
+
+    tickets.service = com.gitblit.tickets.FileTicketService
+
+Your ticket journals are persisted to `tickets/{shard}/{id}/journal.json`.  These journals are stored on the filesystem within your .git directory.
+
+#### Branch Ticket Service
+
+    tickets.service = com.gitblit.tickets.BranchTicketService
+
+Your ticket journals are persisted to `id/{shard}/{id}/journal.json`.  These journals are stored on an orphan branch, `refs/gitblit/tickets`, within your repository.  This allows you to easily clone your entire ticket history to client working copies or to mirrors.
+
+#### Redis Ticket Service
+
+    tickets.service = com.gitblit.tickets.RedisTicketService
+
+Your ticket journals are persisted to a Redis data store.  *Make sure you configure your Redis instance for durability!!*  This particular service is highly-scalable and very fast.  Plus you can use all of the power of Redis replication, should you want.
+
+The main drawback to this service is that Redis is primarily a Unix tool and works best on a Unix server.  While there is a Windows port, sort-of maintained by Microsoft, it is not actively updated.
+
+    tickets.redis.url = redis://(:{password}@){hostname}:{port}(/{databaseId})
+
+**examples**
+
+    tickets.redis.url = redis://localhost:6379
+    tickets.redis.url = redis://:password@localhost:6379/2
+
+### Other Settings
+
+You should also review the following settings before using Gitblit Tickets to understand what controls are available.
+
+#### web.canonicalUrl
+
+    web.canonicalUrl = https://localhost:8443
+
+The Tickets feature sends rich email notifications to those who are participating or watching a ticket.  In order for the links in those emails to work properly, you really should set the canonical web url of your Gitblit install.  This url should be your public url used to browse and navigate the website.
+
+#### tickets.acceptNewTickets
+
+    tickets.acceptNewTickets = true
+
+This setting is used to globally disable manual creation of tickets through the web ui.  You may still create proposal tickets by pushing patchsets.
+
+You may decide to disable creation of new tickets at the repository level in the *Edit Repository* page, however if this global setting is false, it will trump the repository setting.
+
+#### tickets.acceptNewPatchsets
+
+    tickets.acceptNewPatchsets = true
+
+This setting is used to globally disable accepting new patchsets.  If this set false, you can not create proposal tickets BUT you can still create tickets through the web ui, assuming *tickets.acceptNewTickets=true*.
+
+You may decide to disable accepting new patchsets at the repository level in the *Edit Repository* page, however if this global setting is false it will trump the repository setting.
+
+#### tickets.requireApproval
+
+    tickets.requireApproval = false
+
+This setting is the default for requiring an approve review score (+2) before enabling the merge button in the web ui.  This setting is not considered during the push process so an integrator may push a merged ticket disregarding this approval setting.  The setting only affects the web ui and may be configured per-repository.
+
+#### tickets.indexFolder
+
+*RESTART REQUIRED*
+
+    tickets.indexFolder = ${baseFolder}/tickets/lucene
+
+This is the destination for the unified Lucene ticket index.  You probably won't need to change this, but it's configurable if the need arises.
+
+### Setting up a Repository
+
+#### Controlling Tickets
+
+Each repository can accept or reject tickets and/or patchsets by the repository settings.
+
+##### Issue-Tracker, no patchsets
+
+    allow new tickets = true
+    accept patchsets = false
+
+##### Proposals only, no user-reported issues
+
+    allow new tickets = false
+    accept patchsets = true
+
+##### Issue-tracker AND Proposals
+
+    allow new tickets = true
+    accept patchsets = true
+
+##### No tickets whatsoever
+
+    allow new tickets = false
+    accept patchsets = false
+
+#### Controlling Merges
+
+Gitblit has a simple review scoring mechanism designed to indicate overall impression of the patchset.  You may optionally configure your repository to require an approval score for a patchset revision BEFORE the Merge button is displayed/enabled.  This per-repository setting is not respected if an integrator pushes a merge.  This setting is only used to control the web ui.
+
+#### Milestones
+
+Milestones are a way to group tickets together.  Currently milestones are specified at the repository level and are stored in the repository git config file.  Gitblit's internal architecture has all the methods necessary to maintain milestones, but this functionality is not yet exposed through the web ui.  For now you will have to control milestones manually with a text editor.
+
+    [milestone "v1.5.0"]
+        status = Open
+        due = 2014-06-01
+        color = "#00f000"
+
+Please note the date format for the *due* field: yyyy-MM-dd.