Jira Guidelines

This is a guide to using Jira effectively for Apache CloudStack development. This is best practices that we want all contributors to Apache CloudStack to follow. If something is unclear, please don't hesitate to ask on the cloudstack-dev mailing list and/or in the #cloudstack-dev IRC channel on Freenode. (However, please don't uncertainty stop you from filing a bug if you have one – better to file a bug and edit later than to drop it on the floor!)

What Requires a (CLOUDSTACK) Jira Ticket?

Jira is one of the tools that all CloudStack contributors and users depend on to understand the state of the code for released and unreleased versions of the software. While the -dev mailing list is the best place to have discussions about CloudStack development, it's a poor mechanism for tracking work in progress, claiming issues to work on, or assessing/triaging work that needs to be done.

You should file a Jira ticket for:

• New Features
• Updates to existing features
• Bugs
• Desired new features (wishlist)

Note that you should (almost) never commit a patch without an accompanying Jira ticket, with some minor exceptions:

• Correcting bugs, typos, etc., immediately or very soon after submitting a patch.
• Fixing a bug in an unreleased version of CloudStack is OK, but if a bug has been found in a released version of CloudStack, it should be documented. (Other users may still be using that version and may file duplicate/unnecessary bugs if they can't search Jira and find information on it.)

Best Practices for Filing a Ticket

First and foremost, put yourself in the place of someone else trying to solve the issue based on information in the Jira ticket alone. That means put as much information as you can into the ticket so that the next person can work the issue without having to follow up. Even if the ticket is for an issue you plan to work yourself, the more information provided, the better.

The information in Jira tickets is not only used to fix a specific bug. It is also used for:

• Release notes
• By users seeking information about issues they've experienced
• By other developers seeking information about issues they're working on

Jira tickets without a comprehensive description (e.g. Summary only with no text in the Description field) are not acceptable.

Assess Priority

When creating a new Jira ticket, please take a minute to correctly assess the priority of the issue. By default, Jira assigns a new issue a Priority level of Major. In many cases, this is wrong. Please be sure to set the Priority correctly:

• Blocker: Blocks development and/or testing work, production cannot run. Security issues.
• Critical: Crashes, loss of data, severe memory leak.
• Major: Major loss of function, broken feature, returns incorrect information, etc.
• Minor: Minor loss of function, problem with an easy workaround. Wishlist items.
• Trivial: Typos that don't affect comprehension of the UI, misaligned text, etc.

Verify Version(s) of CloudStack Affected

If you run into an issue with a CloudStack release, please make sure you note which version of CloudStack is affected by the bug. If possible, see if the issue is likely to affect prior/upcoming releases of CloudStack as well.

Best Practices for Working Jira Tickets

Once a ticket has been created and assigned, if you're working a ticket there are a few things to keep in mind.

• Update the ticket at regular intervals so that others know the issue is actually being worked on. If a ticket has not been updated in more than 7 days, others may well assume that it is not in progress and may work on the issue independently.
• If a patch has been submitted, please not the Review Board URL/number so that anyone viewing the Jira ticket may check the patch - and so that committers may review and commit the patch, even if it's not specifically assigned to them for review.

Resolving and Closing Tickets

• If a patch has been committed by you, note the commit hash when closing the ticket.
• Close or resolve the ticket once a patch has been committed.