summaryrefslogtreecommitdiffstats
path: root/src/site
diff options
context:
space:
mode:
Diffstat (limited to 'src/site')
-rw-r--r--src/site/design.mkd1
-rw-r--r--src/site/tickets_barnum.mkd79
-rw-r--r--src/site/tickets_overview.mkd145
-rw-r--r--src/site/tickets_setup.mkd119
-rw-r--r--src/site/tickets_using.mkd155
5 files changed, 499 insertions, 0 deletions
diff --git a/src/site/design.mkd b/src/site/design.mkd
index 1f1635a4..9f77e30a 100644
--- a/src/site/design.mkd
+++ b/src/site/design.mkd
@@ -53,6 +53,7 @@ The following dependencies are automatically downloaded by Gitblit GO (or alread
- [libpam4j](https://github.com/kohsuke/libpam4j) (MIT)
- [commons-codec](http://commons.apache.org/proper/commons-codec) (Apache 2.0)
- [pegdown](https://github.com/sirthias/pegdown) (Apache 2.0)
+- [jedis](https://github.com/xetorthio/jedis) (MIT)
### Other Build Dependencies
- [Fancybox image viewer](http://fancybox.net) (MIT and GPL dual-licensed)
diff --git a/src/site/tickets_barnum.mkd b/src/site/tickets_barnum.mkd
new file mode 100644
index 00000000..91f29b63
--- /dev/null
+++ b/src/site/tickets_barnum.mkd
@@ -0,0 +1,79 @@
+## Barnum
+
+*PREVIEW 1.4.0*
+
+Barnum is a command-line companion for Git. It's purpose is to simplify the syntax and ceremony for working with Gitblit Tickets and Patchsets.
+
+The current implementation is a Python script that wraps a native Git executable. It requires Python 3 and native Git. It works well on Windows, Linux, and Mac OS X.
+
+### Fetch
+
+ pt fetch <id> [-p,--patchset <n>]
+
+If *patchset* is specified, the **fetch** command will download the specified ticket patchset to the FETCH_HEAD ref. If *patchset* is **not*** specified, the configured remote will be fetched to download all ticket branch updates - this is the same as <pre>git fetch {remote}</pre>.
+
+### Checkout (co)
+
+ pt checkout <id> [-p,--patchset <n>] [--force]
+
+The **checkout** command fetches and checks-out the patchset to a predetermined branch.
+
+If *patchset* is not specified, the current patchset is checked-out to `ticket/{id}`. If *patchset* is specified, the patchset is checked-out to `patchset/{id}/{patchset}`.
+
+### Pull
+
+ pt pull <id> [-s,--squash]
+
+The **pull** command fetches and merges the ticket patchset into your current branch.
+
+You may specify the `--squash` flag to squash the pulled patchset into one commit. This will leave your working directory dirty and you must stage and commit the pending changes yourself.
+
+### Push (up)
+
+ pt push [<id>] [--force] [-r, --responsible <user>] [-m,--milestone <milestone>] [-t,--topic <topic>] [-cc <user> <user>]
+
+The **push** command allows you to upload a fast-forward update to an existing patchset or to upload a rewrite of an existing patchset (amend, rebase, or squash).
+
+You may set several ticket fields during the push such as *milestone*, *topic*, and *responsible*. Use the *cc* argument to add users to the watch list for the ticket.
+
+One thing to note about the *topic* field is that Gitblit will match the *topic* against the repository bugtraq configuration which allows you to link your ticket with an external issue tracker.
+
+### Start
+
+ pt start <topic>
+ pt start <id>
+
+The **start** command is used to start development of a topic branch that will eventually be pushed to a Ticket.
+
+You must specify what you are starting. If you specify a ticket id, the branch `topid/{id}` will be created. If you specify a topic string, the branch `topic/{topic}` will be created. The main difference will be how the **propose** command treats your branch name.
+
+### Propose
+
+ pt propose [new | <branch> | <id>] [-r, --responsible <user>] [-m,--milestone <milestone>] [-t,--topic <topic>] [-cc <user> <user>]
+
+The **propose** command pushes an initial patchset to an existing ticket OR allows you to create a new ticket from your patchset on push.
+
+If you created your topic branch with the **start** command and you specified an existing ticket id as what you were starting, then Barnum will identify the id from the branch name and assume that is the target ticket for your patchset.
+
+If you created your topic branch with the **start** command and you specified a topic string as what you were starting, Barnum will identify that and specify that as the *topic* push ref parameter, but will still require a proposal target: *new*, *branch*, or *id*.
+
+#### Create Ticket on Push
+
+In order to create a ticket from your patchset, your patchset *must* contain only a *single* commit. The first line of the commit message will specify the ticket title. The remainder of the commit message will define the ticket description.
+
+ Fix null pointer exception in StringUtils
+
+ It is possible to throw a null pointer exception in the trim method.
+ This can be triggered by yada, yada, yada.
+
+After the ticket is created from the single commit, you can push as many additional commits as you want. It is just the first push with one commit that is special.
+
+One helpful tip to note about the *topic* field is that Gitblit will match the *topic* against the repository bugtraq configuration which allows you to link your ticket with an external issue tracker.
+
+### Cleanup (rm)
+
+ pt cleanup <id> [--force]
+
+The **cleanup** command is used to delete ticket branches from your local repository.
+
+The *force* argument is necessary for **cleanup** to actually remove the local branches. Running **cleanup** by itself will identify the branches that can be removed.
diff --git a/src/site/tickets_overview.mkd b/src/site/tickets_overview.mkd
new file mode 100644
index 00000000..f236e51f
--- /dev/null
+++ b/src/site/tickets_overview.mkd
@@ -0,0 +1,145 @@
+## Tickets
+
+*PREVIEW 1.4.0*
+
+Gitblit's Tickets feature is analgous to GitHub/BitBucket Issues+Pull Requests. Gitblit does not make a hard distinction between what is an Issue and what is a Pull Request. In Gitblit, all tickets may have attached commits and there is no need to create a separate, new container to share & discuss these commits. Additionally, there is no need to create multiple Tickets for different versions of the same code - a common practice in other systems.
+
+You can view a screencast of Gitblit Tickets in action [here](https://vimeo.com/86164723).
+
+### Design
+
+The Tickets feature of Gitblit is designed around a few principles:
+
+1. Tickets should be simple enough to use quickly to track action items or user reports
+2. Any ticket can contain commits shared by a contributor
+3. The ticket should be the canonical source of commits related to the ticket (i.e. a fork repository should not be the canonical source of commits)
+4. Additional contributors should be allowed to participate in developing the patchset for a ticket, not just the original patchset author. The ticket should be a container for collaborative branch development, not just for code-review/gating.
+5. Contributors should be able to rewrite commits attached to a ticket without losing history. Contributors should be encouraged to polish, hone, and rewrite as needed to ensure that what eventually is merged is logical and concise.
+
+Gitblit takes inspiration from GitHub, BitBucket, and Gerrit.
+
+#### Ticket Model
+
+Gitblit stores each ticket as a journal (list of changes). A ticket journal is retrieved from the chosen persistence engine and an effective ticket is built by applying the ordered changes from the journal. These changes are usually additive, but in some cases a change may represent a deletion. Tickets are indexed by Lucene against which all ticket queries are executed.
+
+#### Collaboration Workflow
+
+Gitblit uses a 3-repository workflow. This means that Gitblit cuts the *fork* repository out of the collaboration workflow: patchsets are pushed directly to a special branch of the canonical repository, not to a fork. You may also push to fork, if you want, but all collaboration occurs in the canonical repository, not your fork.
+
+#### Persistence Choices
+
+Gitblit's ticket data is based on a ridiculously simple concept: a ticket is the end result of applying a sequence of changes to an empty ticket. Each change is serialized as JSON and stored in a journal. The journal may be a simple text file (`journal.json`) or it may be a Redis LIST or some future persistence type.
+
+All ticket services inherit from the same base class which handles most of the high level logic for ticket management including caching, milestones (stored in .git/config), indexing, queries, and searches.
+
+You can find descriptions of the available persistence services in the [setup][tickets_setup.mkd] page.
+
+#### Limitations
+
+- Ticket data is non-relational to user accounts. If *james* comments on a ticket, *james* is preserved forever in the ticket data. This is similar to git commits which are also non-relational. This could be overcome by writing a tool to deserialize all the journals and rewrite the authors, so it is not impossible to change, but following KISS - ticket data is non-relational to user accounts.
+- The *Branch Ticket Service* does not currently permit ticket journal pushes from clones. This is an area of exploration and may be possible given that a ticket is constructed from an append-only journal of changes.
+- Gitblit does not currently offer commit comments nor line comments, only overall ticket comments .
+
+#### How did GitHub influence the design of Tickets?
+
+**UI.** GitHub has a very efficient, and clean UI for their Issues. It offers the basics and give you labels to fill in the gaps. It is not overly complex.
+
+Gitblit's Ticket querying and discussion ui are modeled after GitHub's ui design.
+
+#### How did BitBucket influence the design of Tickets?
+
+**UI.** BitBucket has a more rigid issue tracker and a clean issue viewing ui. The rigidity makes it more like a traditional issue tracker with status, priority, kind, etc.
+
+Gitblit's Ticket page ui is partially inspired by BitBucket. Gitblit Tickets have state and types, which makes it a more rigid/traditional tracker. Atlassian has also gifted the community with the AUI, a webapp toolkit of CSS & JS. Gitblit has borrowed some of these Apache licensed CSS elements.
+
+**Branch Pull Requests.** BitBucket has a very cool feature of creating a pull request from a branch within the same repository. GitHub may also be able to do this. Gitblit does not currently allow you to create a ticket from an existing branch, but Gitblit tracks ticket commits using normal branches with the canonical repository.
+
+#### How did Gerrit influence the design of Tickets?
+
+**Patchsets.** Gerrit employs a clever patchset workflow that requires repeated use of `git commit --amend` to hone and polish a commit until it is ready for merging to the proposed integration branch. This technique is a much improved analog of patch revision.
+
+After working with this design for many months and dogfooding dozens of tickets with hundreds of amends, rebases, and squashes, I have concluded that this workflow doesn't work like I wanted it to for active, in-development code. It is best suited for it's original intention: code-review. It also introduces many, many refs.
+
+Gitblit has adopted Gerrit's three-repository workflow and *magic ref* design for pushes of new ticket patchsets or rewrites of existing ticket patchsets.
+
+### Nomenclature
+
+1. The organizational unit of the Gitblit Tickets feature is the *ticket*.
+2. A *ticket* can be used to report a bug, request an enhancement, ask a question, etc. A ticket can also be used to collaborate on a *patchset* that addresses the request.
+3. A *patchset* is a series of commits from a merge base that exists in the target branch of your repository to the tip of the patchset. A patchset may only contain a single commit, or it may contain dozens. This is similar to the commits in a *Pull Request*. One important distinction here is that in Gitblit, each *Patchset* is developed on a separate branch and can be completely rewritten without losing the previous patchsets (this creates a new patchset).
+4. A *ticket* monitors the development of *patchsets* by tracking *revisions* to *patchsets*. The ticket alslo monitors rewritten patchsets. Each *patchset* is developed on it's own Git branch.
+
+Tracking *patchsets* is similar in concept to Gerrit, but there is a critical difference. In Gerrit, *every* commit in the *patchset* has it's own ticket **AND** Git branch. In Gerrit, *patchsets* can be easily rewritten and for each rewritten commit, a new branch ref is created. This leads to an explosion in refs for the repository over time. In Gitblit, only the tip of the *patchset* gets a branch ref and this branch ref is updated, like a regular branch, unless a rewrite is detected.
+
+If you prefer the Gerrit-style workflow, you can achieve a fair approximation by only pushing single commit patchsets and always amending them. You will not be able to chain tickets together, like you can chain reviews in Gerrit.
+
+### Types of Tickets
+
+Gitblit has two primary ticket types with a subtle distinction between them.
+
+1. *Proposal Ticket*. This ticket type is created when a contributor pushes a single commit to Gitblit using the **for** magic ref. The title and body of the commit message become the title and description of the ticket. If you want to adopt a Gerrit-style workflow then you may *--amend* this commit and push it again and again. Each *--amend* and push will update the Ticket's title and description from the commit message. However, if you push new commits that build on the initial commit then this title/description updating behavior will not apply.
+
+2. *Request Ticket*. This is a ticket that is manually created by a user using the web ui. These tickets have assignable types like *Bug*, *Enhancement*, *Task*, or *Question*.
+
+The only difference between these two ticket types is how they are created (on-push or through the ui) and the aforementioned special behavior of amending the initial commit. Otherwise, both types are identical.
+
+### Why not GitHub-style Pull/Merge Requests?
+
+GitHub-style Pull Requests require the following workflow:
+
+1. Fork RepoA -> MyRepoA
+2. Clone MyRepoA
+3. Create branch in MyRepoA clone and hack on contribution
+4. Push new branch upstream to MyRepoA
+5. Open Pull Request from MyRepoA -> RepoA
+6. RepoA owner pulls from MyRepoA
+7. RepoA owner pushes merge to RepoA
+
+Gitblit's flow looks like this:
+
+1. Clone RepoA
+2. Create branch in RepoA clone and hack on contribution
+3. Push to magic branch of RepoA
+4. RepoA owner pulls from RepoA
+5. RepoA owner pushes merge to RepoA
+
+The Gitblit workflow eliminates the 4-repository design of a GitHub pull request (canonical, canonical working copy, fork, & fork working copy) in favor of a 3-repository design (canonical, canonical working copy, clone working copy).
+
+You might wonder: is it a good idea to allow users to push into the canonical repository? And the answer is, it's no different than a GitHub pull request. When you open a GitHub pull request from MyRepoA to RepoA, your code is already being pushed to a private branch in RepoA (*refs/pull/{id}/head* and *refs/pull/{id}/merge*) so effectively you are already pushing into RepoA - you are just using an extra repository and the web ui to do it. By pushing directly to the canonical repository, you save server resources and eliminate the web ui step.
+
+Additionally, because the patchset is not linked to a user's personal fork it is possible to allow others to collaborate on development.
+
+## Status
+
+The Tickets feature is highly functional but there are several areas which need further refinements.
+
+#### What is working
+
+- Ticket creation and editing
+- Ticket creation on patchset push
+- Comments with Markdown syntax support
+- Rich email notifications
+- Fast-forward patchset updates and patchset rewrites
+- Voting
+- Watching
+- Mentions
+- Partial milestone support
+- Querying
+- Searching
+- Is Mergeable test on view ticket page load
+- Close-on-push of detected merge
+- Multiple backend choices
+- Server-side merge (testing)
+
+#### TODO
+
+- need a My Tickets page
+- web ui for adding, editing, and deleting miletones
+- continue cleanup of code and templates
+- would be nice to have a collapsible ticket description (e.g. AUI expander)
+- would be nice to edit a comment
+- would be nice to delete a comment
+- Groovy hook points major ticket changes (new, close, patchset change)
+- REST API for tooling
+- Might be nice to process Markdown previews client-side rather than round-tripping to Gitblit (another stateful example). Perhaps using AngularMarkdown?
+- Would be nice to have a tool to import/export journals between services. All the journals use the same format so this should be very straight-forward to migrate/convert them between services.
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.
diff --git a/src/site/tickets_using.mkd b/src/site/tickets_using.mkd
new file mode 100644
index 00000000..71a4ebec
--- /dev/null
+++ b/src/site/tickets_using.mkd
@@ -0,0 +1,155 @@
+## Using Tickets
+
+*PREVIEW 1.4.0*
+
+### Creating Standard Tickets
+
+Standard tickets can be created using the web ui. These ticket types include *Bug*, *Enhancement*, *task*, and *Question*.
+
+### 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.
+
+*Why should 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 changes using Git, not your browser.
+
+*Who can create a proposal ticket?*
+
+Any authenticated user who can clone your repository.
+
+ git checkout -b mytopic
+ ...add a single commit...
+ git push origin HEAD:refs/for/new
+ git branch --set-upstream-to={remote}/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.
+
+*Who can create the first patchset for an existing ticket?*
+
+Any authenticated user who can clone your repository.
+
+ git checkout -b mytopic
+ ...add one or more commits...
+ git push origin HEAD:refs/for/{id}
+ git branch --set-upstream-to={remote}/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
+3. The person set as *responsible*
+4. Any user with write (RW) permissions to the repository
+
+
+ git checkout ticket/{id}
+ ...add one or more commits...
+ git push
+
+### Rewriting a Patchset (amend, rebase, squash)
+
+*Who can rewrite a patchset?*
+
+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}
+ ...amend, rebase, squash...
+ git push origin HEAD:refs/for/{id}
+
+### Ticket RefSpecs
+
+Gitblit supports two primary push ref specs: the magic ref and the patchset ref.
+
+#### to create a new proposal ticket
+
+| ref | description |
+| :------------------- | :------------------------------------------- |
+| refs/for/new | new proposal for the default branch |
+| refs/for/default | new proposal for the default branch |
+| refs/for/{branch} | new proposal for the specified branch |
+
+#### to add a proposal patchset (first patchset) to an existing ticket
+
+| ref | description |
+| :------------------- | :------------------------------------------- |
+| refs/for/{id} | add new patchset to an existing ticket |
+
+#### to add commits to an existing patchset
+
+| ref | description |
+| :--------------------------- | :----------------------------------- |
+| refs/heads/ticket/{id} | fast-forward an existing patchset |
+
+
+#### to rewrite a patchset (amend, rebase, squash)
+
+| magic ref | description |
+| :------------------- | :------------------------------------------- |
+| refs/for/{id} | add new patchset to an existing ticket |
+
+### Ticket RefSpec Tricks
+
+Gitblit supports setting some ticket fields from the push refspec.
+
+ refs/for/master%topic=bug/42,r=james,m=1.4.1,cc=dave,cc=mark
+
+| parameter | description |
+| :-------- | :-------------------------------------------------------------- |
+| t | assign a *topic* to the ticket (matched against bugtraq config) |
+| r | set the *responsible* user |
+| m | set the *milestone* for patchset integration |
+| cc | add this account to the *watch* list (multiple ccs allowed) |
+
+#### 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.
+
+ git push origin HEAD:refs/for/12%cc=james,cc=mark,t=issue-123
+
+Add some commits to ticket *123* patchset *5*. Set the milestone to *1.4.1*.
+
+ git push origin HEAD:refs/heads/ticket/123/5%m=1.4.1
+
+### Merging Patchsets
+
+The Gitblit web ui offers a merge button which *should work* but is not fully tested. Gitblit does verify that you can cleanly merge a patchset to the integration branch.
+
+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).
+
+ git pull origin master
+ git checkout -b ticket-{id} master
+ git pull origin ticket/{id}
+ git checkout master
+ git merge ticket-{id}
+ git push origin master
+
+### Closing Tickets on Push with a Completely New Patchset
+
+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.
+
+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).
+
+### Reopening Tickets with Patchsets
+
+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.
+
+This allows you to continue the discussion and create a new patchset that hopefully resolves the need.
+
+**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.
+
+### Reviews
+
+Gitblit includes a very simple review scoring mechanism.
+
+- +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.
+
+If the patchset is updated or rewritten, all reviews are reset; reviews apply to specific revisions of patchsets - they are not blanket approvals/disapprovals.