One of things that I had to learn about when joining the TomEE open source project was JIRA. JIRA is an issue tracking system with some light project management. It’s a great tool for keeping track of who is working on what and what bugs or issues need to be addressed.
Note: JIRA isn’t an acronym it’s a truncation of the word, Gojira which is the real Japanese name for Godzilla. The folks that created JIRA chose the name as a tongue-in-cheek jab at their biggest rival at the time, Bugzilla.
When you join the TomEE community you will end up using JIRA a lot and you’ll find it very useful, but it may seem a little bit intimidating at first. There is a lot of information and fields on a JIRA issue. No worries! This article will explain all those fields and their meaning.
Section 1: The JIRA Instance
The first thing you need to do is find TomEE’s JIRA instance (our JIRA web page). In a web browser enter the TomEE JIRA URL.
When you first arrive at the JIRA instance it will look like the following. This is the Issues Page.
1. The Main JIRA Pages
There are three major pages in our JIRA instance: Issues, Reports, and Components. You can navigate to any one of them using the links on the far left of the landing page.
Reports Page
The Reports Page is interesting. It provides updated health information on the project. The project leads will use this to assess how well things are going at a macro level.
Components Page
The Components Page displays labels that have been assigned to major efforts in the past and present. We’ll talk about this and how its used in more detail later (see the “Component/s” subsection).
Issues Page
The Issues Page is the one we are primarily interested in at this time. It’s the page you should be looking at right now. It shows a listing of all the JIRA Issues for the TomEE project. Make sure the Issues Page is selected.
- Select the “Issues” link on the far left
Section 2: The JIRA Issues Page
The Issues page can be broken up into three major sections: Main Navigation Pane, Issue List Pane, and JIRA Detail Pane.
1. The Main Navigation Pane
The Main Navigation Pane contains the links to all three pages (Reports, Components, and Issues) just discussed.
2. The Issues List Pane
The Issues List Pane shows all the Issues according to whatever Filters you set up. The Basic Filter, which is the default, will show the Issues ordered by their priority. You can change the basic filter by clicking on the “Switch filter” dropdown box (see the arrow labeled “Basic Filters”).
- Click on the “Switch filter” dropdown box
In addition to the basic filters shown above, you can easily get access to more filters by clicking on the “View all issues and filters” link (see the arrow labeled “More Filters”). When you click on this link it exposes many more filters based on fields in the Detail Pane. Once you understand what all these fields mean, you can use these additional filters to search for exactly the kind of JIRA issue that interests you (see “1. The Details Section of a JIRA Issue“).
- Click on the “View all issues and filters” link.
After you have clicked on the “View all issues and filters” link, the basic filters are moved over to the left side panel and more filters are shown above the Issues List and Issue Detail Panes. By default, you are given a few more filters to work with: “Project”, “Type”, “Status”, “Assignee” and text search. You can, however, add even more filters to the filter section by clicking on the “More” button. There is basically one filter for every field in the Issue Detail Pane.
3. The JIRA Issues List Pane
Every Issue that is filed in JIRA has a unique identifier that has two parts, the project identifier (e.g. “TOMEE”) and a 4 digit issue number unique within our project. You will usually refer to issues by their identifier (e.g. “TOMEE-2365”). The issue identifier is shown on every issue listed (see the orange arrow labeled “Identifier”).
In addition, every issue has a Type icon which tells you if the Issue is a Bug, Test, Improvement and so on. The exact meaning of these issue types is discussed later in the section “The JIRA Issue Types and what they mean”. Last is the title (see the arrow labeled “Title”) which is set by the user when creating the issue.
Section 3: The JIRA Issue Detail Pane
The Issue Detail Pane shows all the information associated with a single Issue. It is the primary topic of this the article and so we will spend a considerable amount of time explaining all of its sections and their fields. The Issue Detail Pane can be a bit intimidating at first because it contains so much information but fear not. It is divided neatly into four major areas and each area is easy to understand once you know the purpose of the fields it contains.
The JIRA Detail Pane is divided into four major sections: Details, Description, Sub-Tasks, and Activities.
1. The Details Section of a JIRA Issue
The Details Section provides concise information about the JIRA ticket at a glance. The fields in the Details Section can also be used to filter the JIRA tasks, as discussed earlier in the section titled, “2. The Issues List Pane“.
The JIRA Issue Types and what they mean
In the image below, the “Type” field has a document icon followed by the word “Documentation.” This tells you that this work is related to TomEE documentation.
In addition to “Documentation”, there are several other types of JIRA issues. Here is a full list of issue types and how we use them.
A “Bug” is exactly what you would think it is. It’s something that is broken or otherwise not working correctly. Examples include:
- A thread locking problem
- A broken link in documentation
Bugs can be quick wins, as in the case of the “broken link” or they can become very involved as in the “thread locking” bug. Know your limits. Start with something simple and work up from there.
A “Dependency upgrade” means that some third-party library or tool has been updated and the update needs to be implemented in TomEE. Examples include:
- Apache Johnzon, a JSON processing API, has a new version
- A new version of OpenJDK was released and TomEE needs to support it.
Usually, a dependency upgrade requires a bit of experimentation. You update your local clone with the new version and run the test suite to see if anything breaks.
Note: If the term “clone” is unknow to you then make sure you read the post “It’s Easy! Get the TomEE Source Code and Join the Community” which explains what the term means.
At TomEE we are very enthusiastic and appreciative of contributors who work on Documentation issues. Documentation takes many forms including README.md files, code comments, or entire web pages. Examples include:
- Create an AsciiDoc version of a specific Readme.md file
- Add information about using Maven with TomEE on the Web site
- Improving the code comments on a specific component of TomEE
I can’t stress enough the importance of improving TomEE’s documentation. This is a great place to start for people new to the project because it’s not very complicated, won’t break a build, and is a quick win.
The article “How to Contribute to the TomEE Website” by Cesar Hernandez provides excellent guidance and advice on contributing to the improvements of the TomEE web site.
An “Improvement” issue is anything that can be made better but is not a bug or new feature. Examples include:
- Make parameters final and use the diamond operator on this class
- Clarify the text of the exception message
We can always make TomEE better and attacking these kinds of minor improvements can make a huge difference in the quality of the software. It’s an easy way to get started.
A “New feature” can be fun, but they also are a lot of work and should not be taken on lightly. Examples include:
- Enable JACC (Java Authorization Contract for Containers) on Servlets
- Add Ear-wide @AppliationScoped annotation bean option
New features can take days, weeks, or even months to implement. I don’t recommend working on a “New Feature” issue if you just joined TomEE unless you have a lot of expertise in that area.
A “Task” is kind of a grabbag category that is used when there isn’t a clear type for an issue. A Task can be just about anything but should be used sparingly, so I’m not going to go into details about it here.
One of the best ways to learn new software is to work on a “Test” issue. We use a couple of test frameworks including JUnit for unit tests and Arquillian for integration tests. Unit tests, in particular, can be a great place to get started. They tend to be focused and, on the whole, not too challenging.
A “Wish” issue is for new feature requests. Usually, a feature request is created after there has been some discussion on the mailing list. Examples include:
- Optional ‘EAR-wide’ CDI Extensions
- Strongly typed API for configuration
We are always open to ideas even if we don’t have the resources to work on those things right away. Don’t be shy. Share your vision!
Some issues require so much work that they have to be broken down into sub-tasks. You’ll see “Sub-task” issues nested under other issues. When an issue has a collection of sub-tasks it is often referred to as an “Epic”. Examples of sub-tasks include:
- Create a MicroProfile Config Example
- Add README.adoc to pojo-webservice
Many Epics are created specifically for new members of the TomEE community. It really is the best place to get started.
The JIRA Priorities and what they mean
Triage, the process of prioritizing work, is important to open source projects. You want to know if the problem you are looking at breaks builds or is something far less serious. The following shows how the “Priority” of the JIRA issue is declared.
A higher priority doesn’t always mean its something breaking the system. It might be an indication of a major initiative. There are several levels of “Priority” and the meanings are pretty straight forward.
A “Blocker” is an issue that is preventing other work from being done. You can consider it a “bottleneck” type of problem.
A JIRA issue with a “Critical” priority is usually caused by a bug that is breaking the system builds or preventing TomEE from running properly. Critical JIRA Issues will likely be tackled by experienced TomEE contributors. This is probably not the type of issue you want to take on when first joining the project.
A JIRA issue that is marked as “Major” is important, but is probably not breaking things like a Critical issue. Along with “Minor”, it’s the most common priority on the TomEE project. You can take these on, but they are usually time sensitive or large in scope.
“Minor” issues are usually “nice to have” improvements to code or documentation. You should consider tackling a couple of “Minor” issues when you first join the community. That way, you can take your time to understand the issue better and figure out a solution.
Trivial issues tend to be issues that could be considered more as annoyances than as problems. I tend to think that the Trivial issues are some of the best issues to get new people started.
The Affect Version, Category, and Label fields in JIRA
The “Affect Version”, “Category”, and “Label” fields are convenient for giving context to a JIRA issue and making issues within that context easy to find.
Affects Version/s
Sometimes it useful to identify which version of TomEE that the issue applies to. A lot of people continue to use slightly older versions of TomEE and a problem can be limited to those older versions. When this is the case you can use the “Affects Version/s” field to be more precise.
Fix Version/s
While an issue may affect one or more versions, we are not always going to implement a solution for every version. It may make sense to only implement a solution on the most recent version or an older version.
Component/s
The components field is for identifying a major part of TomEE that needs work. There is an entire page dedicated to defining components which you can find in the Main Navigation Pane (see the section “1. The Main JIRA Pages“).
Labels
The Labels are meant to be used for just about anything. TomEE only uses one – at present – the “Pull-Request has been issued” label. A Pull-Request is a request made by a contributor when they have code they want to contribute back to the main repository. We’ll cover Pull-Requests in a future edition of this blog.
The JIRA Status, Assignee, Reporter, and Resolution
You always want to check the status of a JIRA issue before you consider taking it on. In general, the only status that should concern you is “Open” and only if the issue is also marked “Unresolved” and “Unassigned”. That is exactly the case shown in the screen shot below.
JIRA Assignee
The “Assignee” is the person who has agreed to work on the issue. Epics, which contain sub-tasks are usually not assigned to any one person, but the sub-tasks are.
JIRA Reporter
The “Reporter” is the person who created the JIRA issue in the first place. There are a limited number of reporters on the TomEE project. Use the mailing list to request that a JIRA issue be created when you feel it’s needed.
JIRA Status
There are five kinds of Status each with a specific meaning.
The status of an issue is “Open” when it has yet to be addressed.
Any JIRA issue with a status of “In Progress” has already been assigned and is being worked on.
We are all human and sometimes we find out that something we did, we didn’t do correctly. In the case of a JIRA issue that was “Closed” but found not to be fixed, it can be “Reopened”.
Ultimately we want a JIRA issue to have a status of “Closed” but first we have to have our work reviewed by a peer and committed to the project. So when you think you have finished work on a JIRA Issue, mark it “Resolved” and then create a Pull-Request (i.e. a request to have your code committed to the apache/tomee repository) which will be discussed in more detail in a future article.
If a JIRA ticket is successfully resolved and the code is committed to the main project than its status can be changed to “Closed”. Another possibility is that a JIRA Ticket was rejected for some reason in which case it can be marked as “Closed”.
Resolution
The “Status” tells you the disposition of a JIRA issue, but it doesn’t explain why it became “Closed” or “Resolved”. That’s the job of the “Resolution” Field.
There are close to two dozen different resolutions that can be given to a JIRA issue (see image right) but there are no hard and fast rules for which resolutions you should use. Use your best judgment.
The meaning of Votes and Watchers on JIRA Issues
The Votes and Watchers fields give you an indication of the importance of an issue to the community.
JIRA Issue Votes
Voting allows a project to crowdsource the priority of issues. It’s not used much in TomEE. You can vote and un-vote for an issue using the “More” dropdown menu just above the “Details” section.
JIRA Issue Watchers
Watchers are alerted by email of changes to a JIRA issue. This can be especially useful if the issue is a “Blocker”. It’s also good to be a “Watcher” if you have experience with or expertise in the issue so that you can advise and comment if needed when alerted to changes.
2. The Description Section of a JIRA Issue
The Description section is really comprised of three sub-sections: Description, Attachments, and Issue Links.
JIRA Description Subsection
The Description subsection allows the Reporter, Assignee, and others to describe and discuss the JIRA issue in free-flowing text.
You can edit the Description Subsection by clicking on the text area. It’s a good idea to be as specific as possible when describing an issue.
JIRA Attachments
Attachments can be used for Java code files, documents, and images. You might attach a JAR or .java file that is important to the discussion or a PDF or screenshots.
JIRA Issue Links
Issue Links are links to related issues, Confluence pages, or web links. You might for example put in a link to another JIRA issue that is blocking or is blocked by the current issue. Sometimes, if an issue has a duplicate it will be linked. Confluence is like a wiki but is not used by the TomEE project.
The plus sign in the upper right corner of the Issue Links subsection can be clicked to launch a dialog window where you can search for issues to link or add web links.
3. The Sub-task Section of a JIRA Issue
Sometimes it’s helpful to break an issue up into sub-tasks. Sub-tasks are used in volume with what are called Epics.
An Epic is generally not assigned to a specific contributor, rather its sub-tasks, each of which acts as its own JIRA Issue, can be assigned, worked on, and completed.
Epics are the primary way work is assigned to people new to TomEE. They are designed to provide tasks that are narrow in scope, less complex, and easy to complete. They are quick wins in many cases and its a sub-task of an Epic which will probably be your first JIRA issue.
4. The Activities Section of a JIRA Issue
The Activities section serves several purposes but the TomEE project only takes advantage of a couple of them, namely: “Comments”, “History”, and “Activity”.
JIRA Comments Tab
As the name suggests, comments are comments made about the Issue by community members. To add a comment click on the “Comment” button indicated by the orange arrow in the above image.
JIRA History Tab
Every time a change is made to the Description subsection, the change is recorded. You can see that record in the “History” tab. It shows the original content before the change and next to that the update.
JIRA Activity Tab
Whenever something is changed on the JIRA issue it is logged and can be found in the “Activity” Tab.
Conclusion
After reading this entire article you might be feeling a bit overwhelmed. Don’t. Think of this blog post as a reference that you can come back when needed.
As mentioned earlier, the TomEE project uses JIRA to track all of the work we do on the open source project including code, examples, and documentation. JIRA will become a regular part of your work effort and with time will become second nature. No one expects you to grasp everything at once, so don’t be afraid to try.
In the future will cover the process of asking for, and being assigned a JIRA issue. We’ll also cover how you go about working on the code base or documentation and tracking your effort in JIRA. Finally, we’ll cover how to contribute your code back to the main TomEE branch. Remember, take all this in with baby steps. There is no hurry. We are not going anywhere.
