QuickBuild now integrate with [Trac|http://trac.edgewall.org] natively. The integration features:
* Hyperlink the Trac ticket id in commit messages to corresponding JIRA pages
* Generate an issues report from commit messages
* Progress/update the issues from commit messages
* Release a milestone of a project in Trac
* Create an issue to Trac based on step condition
This page will describe how to integrate Trac in QuickBuild.
*On This Page*
{toc:class=pagetoc|style=disc|indent=20px|maxLevel=4}
{info}
Supported Trac version: 0.11 or higher.
{info}
h3. Basic Integration
To enable the integration:
# *Install and enable XML RPC plugin for Trac.* This plugin and its installation guide can be found at below link:
http://trac-hacks.org/wiki/XmlRpcPlugin
# *Configure Trac Server on configuration settings tab.*
!trac-settings.png!
Below lists the descriptions of these properties:
||Property||Description||
|Server URL|Defines the server url. you can test it by adding "/rpc", for example, if the server url is: {html}http://localhost/trac/project{html}, open below url in your browser: {html}http://localhost/trac/project/rpc{html}, and if the "Remote Procedure Call (RPC)" page can be displayed correctly, this url can work in QuickBuild. |
|User Name|The user should have TICKET_VIEW permission. If you want to update issues from QuickBuild, the user should also have TICKET_MODIFY permission.|
|Password|The password for the user.|
|Ticket Pattern|Defines the ticket pattern which will be used to extract the ticket id from commit messages. The ticket pattern here uses [Java regular expression|http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html] to match the ticket ids. By default, below pattern will match #123 or ticket:123.
{code}
(?<!\:)(?:#|ticket:)\d+
{code}
|
After doing these, the issues keys mentioned in commit messages will be hyperlinked:
!issues-on-overview.png!
and a ticket report will be displayed in Build tab:
!issues.png!
you can also find all related issues from a specified version and view the changes for an issue:
!issues-changes.png!
After configured the Trac server in the configuration settings, below steps are available to add in your build workflow:
* Update Issue Step
* Release Version Step
* Create Issue Step
!trac-steps.png!
h3. Advanced Integration
Besides the basic integration, QuickBuild also features:
* Update tickets mentioned in commit messages directly
* Cooperate with Trac to manage both Trac and QuickBuild version
* Release a Trac milestone and also update the milestone field of tickets mentioned in commit messages which can help you to generate the Release Notes easily.
h4. Update Tickets
To update tickets from the commit messages, *Update Trac Ticket* step should be added to your build workflow. And when QuickBuild find any [commit commands|Commit Command] in the commit messages, QuickBuild will submit them to Trac to update or progress the tickets.
*NOTE:*
* To update issues, QuickBuild need map SCM committer to Trac user as we want to make sure the updates in Trac are made by the same person who submits the commit commands.
* This step should be defined after your checkout step.
* QuickBuild will update all tickets which are requested from the commit comments from *previous successful* build.
* If a ticket updated manually after committed, this tickets will not be updated then.
h5. Associated SCM user with Trac user
If the username and password in your SCM, QuickBuild and Trac are same, the association between them is already set up. Or you have to associate them together:
* If the SCM user is different with QuickBuild user, you need associate them in your configuration Repository settings.
* If the Trac user is different with QuickBuild user, you need associate them in Administration -> User Management tab (if you are administrator) or go to My tab (if you are normal user) and enable and input your Trac account like below:
!trac-account.png!
h5. Customize Commit Command
The [commit command|Commit Command] can be customized in step definition:
!customize-commands.png!
The _commit command_ property defines the commit command which you can change to meet your company requirements. And the _update attributes_ here are what you want to change in your Trac when executing the commit command. For example, when executing _accept_ commit command above, QuickBuild will update the ticket status and change it to accept, also will update the owner to the command committer which is same as the SCM committer.
Below section will discuss the attributes available.
h5. Command Attributes
The command attributes for Trac are defined by the Trac server. You may ask your Trac administrator for available attributes or reference [http://trac.edgewall.org/wiki/TracTickets]. By default Trac installation, the attributes include:
* *type* - The nature of the ticket (for example, defect or enhancement request)
* *reporter* - The author of the ticket.
* *summary* - A brief description summarizing the problem or issue.
* *description* - The body of the ticket.
* *component* - The project module or subsystem this ticket concerns.
* *version* - Version of the project that this ticket pertains to.
* *status* - What is the current status? One of new, assigned, closed, reopened or whatever you add/customize in the Trac.
* *resolution* - Reason for why a ticket was closed.
* *priority* - The importance of this issue, ranging from trivial to blocker.
* *milestone* - When this issue should be resolved at the latest.
* *owner* - Principal person responsible for handling the issue.
* *cc* - A comma-separated list of other users or E-Mail addresses to notify.
* *comment* - Add a comment to the ticket
These attributes can be used not only in the _Update Trac Ticket_ step, but also in the [commit commands|Commit Command].
Besides the attributes specified in the [commit command|Commit Command], the *_Extra Attributes_* in the step definition is used to add some common attributes you want. For example, you want leave a comment against each updating, you may define the extra attributes like:
{code}
comment = Updated in build ${build.getVersion}
{code}
Each attribute should use one line and you can use script (see the example above) which gives you more flexibility to control the value you want to input to the issue.
h4. Release Milestone
To release milestone to Trac server, *_Release Trac Milestone_* step should be added to your build workflow. This step will set or update the complete date of milestone, if the milestone does not exist in Trac, QuickBuild will create it and add it to Trac.
This step will also update the milestone field of all tickets mentioned in the commit messages from previous successful build.
Although, the released milestone uses build version, you can still manage the milestone by yourself from Trac side and let QuickBuild use them.
h5. Use Trac milestone as build version
To use Trac milestone as your build version is very simple, you just need go to configuration settings and set the property _Next Build Version_ to _Use next unreleased milestone from Trac_. By doing this, the next build version will use the default next milestone which defined in Trac.
!trac-nextversion.png!
h4. Create Ticket
By adding _Create Trac Ticket_ step, you can create a ticket to Trac based on your step condition which can be used to manage the build status in the Trac.
* Hyperlink the Trac ticket id in commit messages to corresponding JIRA pages
* Generate an issues report from commit messages
* Progress/update the issues from commit messages
* Release a milestone of a project in Trac
* Create an issue to Trac based on step condition
This page will describe how to integrate Trac in QuickBuild.
*On This Page*
{toc:class=pagetoc|style=disc|indent=20px|maxLevel=4}
{info}
Supported Trac version: 0.11 or higher.
{info}
h3. Basic Integration
To enable the integration:
# *Install and enable XML RPC plugin for Trac.* This plugin and its installation guide can be found at below link:
http://trac-hacks.org/wiki/XmlRpcPlugin
# *Configure Trac Server on configuration settings tab.*
!trac-settings.png!
Below lists the descriptions of these properties:
||Property||Description||
|Server URL|Defines the server url. you can test it by adding "/rpc", for example, if the server url is: {html}http://localhost/trac/project{html}, open below url in your browser: {html}http://localhost/trac/project/rpc{html}, and if the "Remote Procedure Call (RPC)" page can be displayed correctly, this url can work in QuickBuild. |
|User Name|The user should have TICKET_VIEW permission. If you want to update issues from QuickBuild, the user should also have TICKET_MODIFY permission.|
|Password|The password for the user.|
|Ticket Pattern|Defines the ticket pattern which will be used to extract the ticket id from commit messages. The ticket pattern here uses [Java regular expression|http://java.sun.com/j2se/1.5.0/docs/api/java/util/regex/Pattern.html] to match the ticket ids. By default, below pattern will match #123 or ticket:123.
{code}
(?<!\:)(?:#|ticket:)\d+
{code}
|
After doing these, the issues keys mentioned in commit messages will be hyperlinked:
!issues-on-overview.png!
and a ticket report will be displayed in Build tab:
!issues.png!
you can also find all related issues from a specified version and view the changes for an issue:
!issues-changes.png!
After configured the Trac server in the configuration settings, below steps are available to add in your build workflow:
* Update Issue Step
* Release Version Step
* Create Issue Step
!trac-steps.png!
h3. Advanced Integration
Besides the basic integration, QuickBuild also features:
* Update tickets mentioned in commit messages directly
* Cooperate with Trac to manage both Trac and QuickBuild version
* Release a Trac milestone and also update the milestone field of tickets mentioned in commit messages which can help you to generate the Release Notes easily.
h4. Update Tickets
To update tickets from the commit messages, *Update Trac Ticket* step should be added to your build workflow. And when QuickBuild find any [commit commands|Commit Command] in the commit messages, QuickBuild will submit them to Trac to update or progress the tickets.
*NOTE:*
* To update issues, QuickBuild need map SCM committer to Trac user as we want to make sure the updates in Trac are made by the same person who submits the commit commands.
* This step should be defined after your checkout step.
* QuickBuild will update all tickets which are requested from the commit comments from *previous successful* build.
* If a ticket updated manually after committed, this tickets will not be updated then.
h5. Associated SCM user with Trac user
If the username and password in your SCM, QuickBuild and Trac are same, the association between them is already set up. Or you have to associate them together:
* If the SCM user is different with QuickBuild user, you need associate them in your configuration Repository settings.
* If the Trac user is different with QuickBuild user, you need associate them in Administration -> User Management tab (if you are administrator) or go to My tab (if you are normal user) and enable and input your Trac account like below:
!trac-account.png!
h5. Customize Commit Command
The [commit command|Commit Command] can be customized in step definition:
!customize-commands.png!
The _commit command_ property defines the commit command which you can change to meet your company requirements. And the _update attributes_ here are what you want to change in your Trac when executing the commit command. For example, when executing _accept_ commit command above, QuickBuild will update the ticket status and change it to accept, also will update the owner to the command committer which is same as the SCM committer.
Below section will discuss the attributes available.
h5. Command Attributes
The command attributes for Trac are defined by the Trac server. You may ask your Trac administrator for available attributes or reference [http://trac.edgewall.org/wiki/TracTickets]. By default Trac installation, the attributes include:
* *type* - The nature of the ticket (for example, defect or enhancement request)
* *reporter* - The author of the ticket.
* *summary* - A brief description summarizing the problem or issue.
* *description* - The body of the ticket.
* *component* - The project module or subsystem this ticket concerns.
* *version* - Version of the project that this ticket pertains to.
* *status* - What is the current status? One of new, assigned, closed, reopened or whatever you add/customize in the Trac.
* *resolution* - Reason for why a ticket was closed.
* *priority* - The importance of this issue, ranging from trivial to blocker.
* *milestone* - When this issue should be resolved at the latest.
* *owner* - Principal person responsible for handling the issue.
* *cc* - A comma-separated list of other users or E-Mail addresses to notify.
* *comment* - Add a comment to the ticket
These attributes can be used not only in the _Update Trac Ticket_ step, but also in the [commit commands|Commit Command].
Besides the attributes specified in the [commit command|Commit Command], the *_Extra Attributes_* in the step definition is used to add some common attributes you want. For example, you want leave a comment against each updating, you may define the extra attributes like:
{code}
comment = Updated in build ${build.getVersion}
{code}
Each attribute should use one line and you can use script (see the example above) which gives you more flexibility to control the value you want to input to the issue.
h4. Release Milestone
To release milestone to Trac server, *_Release Trac Milestone_* step should be added to your build workflow. This step will set or update the complete date of milestone, if the milestone does not exist in Trac, QuickBuild will create it and add it to Trac.
This step will also update the milestone field of all tickets mentioned in the commit messages from previous successful build.
Although, the released milestone uses build version, you can still manage the milestone by yourself from Trac side and let QuickBuild use them.
h5. Use Trac milestone as build version
To use Trac milestone as your build version is very simple, you just need go to configuration settings and set the property _Next Build Version_ to _Use next unreleased milestone from Trac_. By doing this, the next build version will use the default next milestone which defined in Trac.
!trac-nextversion.png!
h4. Create Ticket
By adding _Create Trac Ticket_ step, you can create a ticket to Trac based on your step condition which can be used to manage the build status in the Trac.