Introduction #

JIRA is a bug-tracking system developed by Atlassian. It is used by Liferay to accept and also to process bug tickets. Liferay currently uses version 4.4.4.

Liferay JIRA #

Liferay uses JIRA to process bugs and also to accept user-contributed patches. Liferay's JIRA is located at http://issues.liferay.com. Bugs should be reported through this tracker, and with each bug report comes a specific set of steps.

Signing up for an account #

To register an account on JIRA (if you want to file or update and issue), Go here. Accounts are free.

Bug Reporting Standards #

• The bug should not be a general question. Questions belong on the Liferay Forums.
• The bug should be reproduced on the latest version of Liferay CE.
• Steps to reproduce the bug should be given so that the Liferay support team can quickly determine if it is a bug and if it is fixable. Reproduced bugs are assigned to either a code sprint or the product/community backlog for eventual assignment to a developer.
• EE customers should not report bugs to the CE section of the JIRA. Instead, use LESA (note that this link is only accessible to EE customers).
• Bug tickets that cannot be reproduced will be closed.
• It is advised to search through JIRA before posting a ticket -- that way, duplicate tickets can be avoided.
• Screenshots are especially helpful for diagnosing bugs.
• Tickets that cannot be reproduced will be closed.

What are all of those JIRA Fields? #

When filing or updating an issue, there are numerous fields presented. This section documents what each of them mean, and gives guidelines on their use.

Creating a new Issue #

Project #

Select the appropriate project in which the issue resides. For example, for Liferay Community Edition, select PUBLIC - Liferay Portal Community Edition.

Issue Type #

Mark the appropriate selection:

• Bug - For problems with existing functionality.
• Regression Bug - For problems that were once fixed, but have been re-broken
• New Feature - Often confused with "Improvement", a New Feature is a request for functionality unrelated to existing functionality. For example, if you want support for a whole new SSO implementation, this would be a New Feature. If you wanted an additional feature within an existing SSO implementation, this would be an "Improvement".
• Improvement - See above. This applies to existing functionality.
• Task - Normally you would not use this type. It is mainly used for program management or to group several issues together as a single task for a developer.
• Technical Support - For internal use. Ordinary technical support questions should go to the community forums.
• Custom Development - Internal use.
• Developer Assistance Call - Internal use.

Summary #

The one-line summary of the bug. Be very specific about the problem, as this will attract (or not) those that may know how to fix it. For example, Problem with Document Library is not a good summary. This is better: FileNotFound error when opening documents with no parent folder.

Priority/Severity #

An issue has a severity level which indicates its importance. The currently defined severities are listed below.

• Critical - Crashes, loss of data, severe memory leak, security hole, no valid workaround.
• Major - Major loss of function.
• Minor - Minor loss of function, edge case not experienced by most users, or other problem where easy workaround is present.
• Trivial - Cosmetic problem like incorrect spelling or misaligned text.

Some examples:

• Causes data loss (e.g. account data) or data corruption on upgrade with no good workaround - Critical
• Causes Liferay to freeze after a particular operation with no good workaround - Critical
• Allows unauthenticated users to see protected content - Critical
• Crashes Liferay, workaround provided - Major
• Adding 10 document library portlets to a page causes javascript error - Minor
• Missing translation for phrase - Trivial

Components #

Liferay is made up of many feature areas, represented by software components. Here is a list and description of components. Choose the most appropriate functional area where you found the issue. Please do not select - none, as this will prevent the bug from showing up on the appropriate developer's dashboard. You can select as many components you feel are affected.

For security-related bugs, please add the Security component and read below regarding Security Level.

For bugs on or improvements to the liferay.com website, please select "Website Content".

Security Level #

Liferay believes in Responsible Disclosure. This means that when you are creating new bugs related to security vulnerabilities, you give Liferay a chance to respond (evaluate, resolve) security bugs before its details are publically disclosed. For security-related bugs, there are two steps to take:

• Choose a security level of Private, ensuring that the bug is not publically visible (it is only visible to you and Liferay's program management personnel). Once Liferay is able to evaluate and resolve the issue, its details are made public for future reference.  Note that for bugs categorized under Security, this security level may become the default in the future.
• Add the Security category to the bug in the Components field. This will ensure the bug is routed to the appropriate group of people responsible for security issues.

Affects Version(s) #

This is one of the more important fields to get right. Select the software version in which you found the issue. Don't guess as to any other versions it may be present (unless you have verified it). Don't pick the odd-looking versions like "--Sprint - SP" or "2011" or "Product Backlog" - these are used for program management and other workflows. When you see this field include something like "6.1.x", this is an indication that the bug has also been verified as existing in the trunk (i.e. unreleased, bleeding-edge Liferay). You can also select this version if you found the bug in trunk (but most community members are using a released version of Liferay).

If you find a bug in a previous CE (Community Edition) release such as 5.1.2 or 5.2.3, be aware that Liferay is no longer producing new Community Editions based on these earlier CE releases, so you must first verify your bug still exists in the latest CE release (as of January 2011 that would be 6.0.5 GA3). If it still exists, you should select all of the releases in which you verified the bug exists (including the latest). If it no longer exists in the latest CE release, then you won't see a fix as we are no longer producing CE releases based on these legacy branches.

Backport Version(s) and Backport Committed #

These fields are used for program management purposes and you should not select anything here (leave the defaults).

Assignee #

This is read-only and automatically assigned. For new community issues, it is assigned to "SE Support" until the issue is reviewed and assigned to a specific developer.

Environment #

List your OS version, Java version, and any other relevant information for the environment in which you encountered this issue. If you found the issue using a trunk build of Liferay, indicate which SVN revision (you can use 'svn info' from the command line to discover this).

Note that this field is also used in some cases for program management (for example, linking issues to a row in an engineering document such as a PRD). Future versions of JIRA will hopefully make it possible to arbitrarily tag issues with identifiers.

Description #

Here you should list all relevant information for the issue, which will aid someone in reproducing, diagnosing, and fixing the issue. Important items to include:

• Step by step description of how to reproduce the issue, using Liferay. The less steps, the better.
• Screen shots showing the error
• Log file snippets showing the error
• Relevant, trimmed stack traces showing the relevant error. If in doubt, post the whole stack trace, but if there are obvious errors, highlight them but cutting out superfluous, surrounding text.

Attachment #

Here you can attach supporting files like screenshots, log files, etc.

Rank #

This is a non-editable field used for program management purposes.

Technical Documentation Required #

If you believe your issue merits additional documentation (usually for new features or improvements), check this box.

Commenting or Viewing existing issues #

There are other fields used mainly for Liferay staff program management purposes and aren't directly editable or changeable by community members. For issues that you file, you may see updates to these fields. They are documented here for those that are wondering:

Fix Version(s) #

This field is read-only for community members and is used for program management. The field represents the version(s) of Liferay in which this issue is fixed in (or will be fixed in). Sometimes it is set to odd versions like "--Sprint - SP" or a future release version. This indicates the ticket is actively being worked on.

Other settings for this field include (as of January 2011):

• Product Backlog - Used for New Features and Improvements. This indicates that the issue will be handled by Liferay staff at some point in the future (issues are taken from the Product Backlog on a regular basis and put into the Liferay development workflow).
• Issues Backlog - Used for Bugs. This indicates that the issue will be handled by Liferay staff at some point in the future issues are taken from the Product Backlog on a regular basis and put into the Liferay development workflow).
• Community Backlog - This indicates that the issue will not be looked at by Liferay Staff, but can be resolved by any Community member. If you wish to take ownership of this bug, you must first fix and test your fix, then attach the fix as a patch to the bug, and click the "Contribute Solution" link on the issue. Once your solution is verified by the original issue submitter, they must click "Accept Contribution". At that point, the fix will be reviewed by Liferay staff for possible inclusion into a future release, and/or backported to previous releases. You will know this has occurred when you see activity on the issue (such as assigning it to a real developer, or updating the Fixed-In field, etc).
• QA Backlog - Used for program management purposes.

Status #

This is one of the more important fields, and it can take on many values. The field is not directly editable by anyone (including staff). Instead, this field represents the state the issue is in according to Liferay's defined workflow.

• Open - The issue is open and ready for the assignee to start work on it. Newly-filed community issues start in this state.
• In Progress - This issue is being actively worked on at the moment by the assignee.
• Reopened - This issue was once resolved, but the resolution was deemed incorrect. From here issues are either marked assigned or resolved.
• Resolved - A resolution has been taken, and it is awaiting verification by reporter. From here issues are either reopened, or are closed.
• Closed - The issue is considered finished, the resolution is correct. Issues which are closed can be reopened.
• Committed to Subversion - A solution for this feature or issue has been committed to SVN and is ready for code review.
• Inactive - The issue is considered inactive, and can be reactivated. If issues stay inactive for too long, they will be closed.
• Analyzed - The issue has been reviewed and the LOE added to the time estimates. It is now ready to be added to a Sprint during Release Planing
• In Review - Committed code is being reviewed for Liferay standards compliance. This is a pass or fail result.
• Manual Testing -Liferay QA is executing manual test cases related to the issue. This is a pass or fail result.
• Automated Testing - Liferay QA is executing automated test cases related to the issue. This is a pass or fail result.
• Contributed Solution - A solution for this feature has been contributed by our community and is awaiting review for submission. The original submitter must click "Accept Solution" (or reject) for it to move to another state and continue its path toward eventual inclusion into Liferay.
• Community Resolved - Community members have reported and resolved the issue and it is ready for analysis by staff
• Pending Verification - Issue is pending review for inclusion in the queue. It has not be reproduced or checked for accuracy.

Resolution #

This field is set when an issue is resolved. It can be assigned one of many values at the time the bug is resolved:

• Fixed - A fix for this issue is checked into the tree and tested.
• Completed - Resolution for issues that are not bugs (such as tasks)
• Won't Fix - The problem described is an issue which will never be fixed. Look for supporting comments as to why it won't be fixed.
• Duplicate - The problem is a duplicate of an existing issue.
• Incomplete - The problem is not completely described. The original submitter must update the bug with the requested information before anything will happen.
• Cannot Reproduce - All attempts at reproducing this issue failed, or not enough information was available to reproduce the issue. Reading the code produces no clues as to why this behavior would occur. If you have additional information to supply, supply it and re-open the bug.
• Reorganized - This issue is being reevaluated and reorganized.
• Inactive - The problem has been inactive for an extended period of time.
• Expired - An old, untouched issue that no longer applies to the current release. Almost the same as Inactive.
• Next Release - The problem will be fixed in a later release.
• Future Release - The problem will be fixed in a future release.
• On Hold - The problem will be on hold until revisited.

Votes #

This field indicates the number of community members who have "voted" for an issue. Voting is one of the easiest ways to participate in the community. Each community member can vote once for each issue. The more votes an issue has, the higher it appears on program management's radar, and the higher chance the issue has of making into a future release of Liferay.

Watchers #

Community members can subscribe to an issue to receive updates when the issue is edited for any reason. Make sure your email address is correct in your JIRA profile.

Other fields #

There are other miscellaneous fields or columns one might see when browsing a list of issues:

• Key - This is the identifier for the issue. Keys are of the form PROJECT-NAME]-[[NUMBER] where [[PROJECT-NAME] is the abbreviation for the project in which the issue is found. For example, "LPS" for "Liferay Portal Community Edition". [[NUMBER] is a monotonically increasing digit assigned as each issue is created.
• Reporter / Assignee - Identifies the specific user who first reported the issue, and the specific user who is working on an issue. For new issues in Community Edition, the Assignee is always "SE Support".
• Created / Updated - Should be obvious.

Working with JIRA #

For detailed information, you can read the JIRA docs. What follows are some simple tasks that you might wish to do:

Editing your Profile #

You can click on your username at the top-right to change your JIRA preferences. For example, many people want a customized dashboard displayed when they log in. You can do this via the "Manage Dashboard" link on the right once you are in your profile.

Other items include your username and email address. If you wish to receive emails (for example when tickets you are watching are updated), make sure your email address is correct.

Finally, you can set other preferences (for example, default language, number of issues displayed per page, etc).

Searching For Issues #

Click on "FIND ISSUES" at the top menu. Here, a search filter option panel is displayed on the left, with with to set search options. Change the options, and click "VIEW >>" to see the new result. If you find a nice search result you want to save to reference later, you can save it as a custom filter (see below).

Voting for Issues #

To vote for a given issue, follow these steps:

1. Login to issues.liferay.com. If you do not yet have a login, signup here (accounts are free).
2. Find the issue you wish to vote using the JIRA search box, or browse all issues, to identify the individual issue you wish to vote on.
3. Click the link on the upper-right titled Vote:

You may cast a single vote for any issue. The total number of votes is shown in the upper-left of the screen when viewing the issue.

Configuring custom filters #

Once you configure the search to your liking, you can save it as a filter for future reference. To do so, click on "<< View & Hide" (I know, an oxymoron, and also not intuitive). Then, click on "Save as a new filter" to give the filter a name and description. Once saved, the filter appears in the "Filters" drop-down at the upper-right.

A couple of useful filters that have been created for use on the Liferay Community site:

• Latest Patches - shows tickets that have been "Community Resolved", ordered by date (descending)
• New Feature Requests - Shows Improvements and New Features that have been opened in the last month.
• Recently Resolved Tickets - Shows tickets that have been recently resolved/closed in the last week.
• Top Community Issues - Shows all open issues, sorted by Votes.

Subscribing to RSS/Atom feeds #

Any search result can be retrieved as an RSS or XML feed, by clicking on the appropriate link at the top. If you are viewing one of your saved filters, the RSS feed will also be decorated with the filter name and description.

Managing Viewable Columns #

The default set of columns might not be enough for you. For example, you may want to see the number of votes for each issue in the list. To configure the columns you see when browsing issues, click on "Configure your Issue Navigator" to add/remove and rearrange columns.