From: James Moger Date: Tue, 4 Mar 2014 18:17:42 +0000 (-0500) Subject: Documentation X-Git-Tag: v1.4.0~59 X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=5d0f712133cdda37aa43771022e1c681e946d594;p=gitblit.git Documentation --- diff --git a/build.xml b/build.xml index ebc73db8..71e7430b 100644 --- a/build.xml +++ b/build.xml @@ -566,7 +566,7 @@ - + @@ -630,6 +630,7 @@ + @@ -903,7 +904,7 @@ - + @@ -938,6 +939,7 @@ + diff --git a/src/site/tickets_barnum.mkd b/src/site/tickets_barnum.mkd index 91f29b63..909e0881 100644 --- a/src/site/tickets_barnum.mkd +++ b/src/site/tickets_barnum.mkd @@ -1,16 +1,22 @@ ## Barnum -*PREVIEW 1.4.0* +*SINCE 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. +Barnum is bundled with each Gitblit installation and linked on each ticket page in the propose, checkout, and merge instructions. You can download Barnum manually using the following url or using the `/pt` url on your own Gitblit server: + + https://dev.gitblit.com/pt + +This url serves a *zip* or a *tar.gz* of the Python script and a readme file, as appropriate based on the user-agent of the requesting client. + ### Fetch pt fetch [-p,--patchset ] -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 
git fetch {remote}
. +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 
git fetch {remote}
. ### Checkout (co) diff --git a/src/site/tickets_overview.mkd b/src/site/tickets_overview.mkd index f236e51f..485ca06d 100644 --- a/src/site/tickets_overview.mkd +++ b/src/site/tickets_overview.mkd @@ -1,10 +1,12 @@ ## Tickets -*PREVIEW 1.4.0* +*SINCE 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). +### Screencast + +You can view a screencast of [Gitblit Tickets in action](https://vimeo.com/86164723) on Vimeo. ### Design @@ -15,6 +17,7 @@ The Tickets feature of Gitblit is designed around a few principles: 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. +6. Tickets should focus on contribution sharing and communication. The Gitblit Tickets feature is not an elaborate code-review system, although in the future it may evolve to be more competitive for that use. Gitblit takes inspiration from GitHub, BitBucket, and Gerrit. @@ -32,7 +35,7 @@ Gitblit's ticket data is based on a ridiculously simple concept: a ticket is the 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. +You can find descriptions of the available persistence services in [[tickets setup]]. #### Limitations @@ -87,25 +90,27 @@ The only difference between these two ticket types is how they are created (on-p 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 +1. Fork *RepoA* -> **MyRepoA** +2. Clone **MyRepoA** +3. Create **MyRepoA_Clone:topic_branch** and hack on contribution +4. Push **MyRepoA_Clone:topic_branch** upstream to **MyRepoA:topic_branch** +5. Open Pull Request from **MyRepoA:topic_branch** -> *RepoA:integration_branch* +6. RepoA owner pulls **MyRepoA:topic_branch** -> *RepoA:integration_branch* and reviews +7. RepoA owner pushes merged contribution upstream to *RepoA:integration_branch* 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 +1. Clone *RepoA* +2. Create *RepoA_Clone:topic_branch* and hack on contribution +3. Push *RepoA_Clone:topic_branch* upstream to *RepoA:refs/for/[new|id]* +4. RepoA owner fetches & merges branch *ticket/[id]* +5. RepoA owner pushes merged contribution upstream to *RepoA:integration_branch* 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. +*You might wonder:* Is it a good idea to allow users to push into the canonical repository? + +The answer is, it's really not that different from 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. @@ -133,13 +138,12 @@ The Tickets feature is highly functional but there are several areas which need #### 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) +- Implement a My Tickets page (ticket-15) +- Ticket Lifecycle Hooks (ticket-16) +- CRUD pages for Milestones (ticket-17) +- Ticket service migration tool (ticket-19) +- Collapsible ticket description (e.g. AUI expander) +- Edit a comment +- Delete a comment - 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. +- Client-side Markdown previews (AngularMarkdown?) diff --git a/src/site/tickets_setup.mkd b/src/site/tickets_setup.mkd index b1fa7758..ee27b44a 100644 --- a/src/site/tickets_setup.mkd +++ b/src/site/tickets_setup.mkd @@ -1,6 +1,6 @@ ## Setting up Tickets -*PREVIEW 1.4.0* +*SINCE 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. diff --git a/src/site/tickets_using.mkd b/src/site/tickets_using.mkd index 71a4ebec..228cf925 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,11 +8,15 @@ Standard tickets can be created using the web ui. These ticket types include *B ### 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?* @@ -25,7 +29,7 @@ Any authenticated user who can clone your repository. ### 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 magic ref. *Who can create the first patchset for an existing ticket?* @@ -89,7 +93,7 @@ Gitblit supports two primary push ref specs: the magic ref and the patchset ref. | 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 +110,13 @@ Gitblit supports setting some ticket fields from the push refspec. #### 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 @@ -143,13 +147,13 @@ This allows you to continue the discussion and create a new patchset that hopefu ### 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 patchset is updated or rewritten, all reviews are reset; reviews apply to specific revisions of patchsets - they are not blanket approvals/disapprovals. +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.