While all open source tools (i.e. GitHub, Maven, Mailing lists, Java IDEs) used by the TomEE open source community are important, the process of identifying and managing the work done on the project is critical to our success. The tool we use for managing work is the TomEE JIRA issue tracking system.
Note: If you are not already familiar with JIRA tickets or find them confusing, you should read “It’s Easy! The Anatomy of a JIRA Issue” after reading this article. It will help clarify all the information a typical JIRA Issue addresses.
Becoming a part of the TomEE community means contributing your brainpower to help improve the project. Whether you choose to work on code, documentation, or unit tests we want you to know how to get assigned JIRA tickets and then work on them and close them.
In this article, you will learn how the TomEE community uses JIRA in its actual development process. Understanding how we use JIRA isn’t difficult but it is fundamental to contributing to the project. It’s also a skill that will be extremely useful in the workplace.
Section 1: What is JIRA?
JIRA is a software platform used to track issues (bugs, enhancements, new feature requests, etc.) in a software project. Sometimes a company will have JIRA running on its own servers, or hosted by a cloud provider, or managed by some other organization. The TomEE project hosts its JIRA instance (web site) at the Apache Foundation. JIRA is Software as a Service (SaaS) in the same way that Salesforce is SaaS for sales or WordPress is SaaS for blogging and web sites.
Note: In this article and others I use the terms JIRA “issue” and JIRA “ticket” to mean basically the same thing. I won’t claim to be entirely consistent on this effort but I do try to use the word “issue” to describe a problem and “ticket” to describe the JIRA documentation of that problem.
Regardless of where your JIRA system is hosted, the web interface is the same. Every issue you document in JIRA has a ticket – a record – that describes the issue and captures all kinds of information including who discovered it, whether it’s assigned to anyone, and details about the issue. A JIRA Ticket provides ways to track the status of works-in-progress, discuss the issue with others, and even vote on the importance of an issue to the community.
Every time a developer discovers an issue (e.g. bug, enhancement, or new feature request) they should create a JIRA ticket before any work is done on that issue. This ensures that everyone knows what everyone else is working on which helps avoid problems like two people working on the same problem but unaware of each other’s work.
Section 2: Overview of TomEE’s Contribution Workflow
TomEE uses JIRA as part of what we call the “Contribution Workflow”, which is simply the process of identifying, documenting, and implementing solutions to issues. The purpose of this article and the ones that follow is to explain the Contribution Workflow so that you can become a valued part of the TomEE community.
I’ve broken this article into multiple parts so that they can be consumed and referenced according to discrete subprocess within the larger whole. Below is a comprehensive diagram of our Contribution Workflow that I will refer to throughout this and future articles.
The Contribution Workflow can be broken down into six sub-processes: JIRA Ticket, Process Task, Submit Changes, Merge Changes, and Clean Up.
2.1: JIRA Ticket
The JIRA Ticket sub-process is all about discovering issues that need work. In TomEE we try to ensure that every bit of work being done on the documentation and code-base is identified and detailed in JIRA tickets. This sub-process shows how to find issues to work on and the process for initiating work on those issues. The JIRA Ticket sub-process is the topic of this first installment.
2.2: Process Task
This is the part where you do the actual work. Where you get the source code or source documentation, do the work, and document that work in a JIRA ticket.
2.3: Submit Changes
In this part, you make sure that your code compiles and passes tests and then you submit what is called a “Pull-Request” (PR) asking for your work to be reviewed and added to the TomEE project.
2.4: Merge Changes
This is where your work is actually added to the TomEE code-base or documentation. This is ultimately your goal: To produce code that improves TomEE and is included in the project.
2.5: Clean Up
This is the last stage in the process and is just as important as any other. Cleaning up after you are done contributing code is like doing the dishes after serving a wonderful dinner. It’s the less exciting but all too necessary part of the process. After you are done with your work there are some things you need to do to clean up and leave the place nice and tidy for the next person.
2.6: A Quick Reference
Once you are familiar with the process it’s easy to remember, so don’t let the big bad diagram above scare you. Any process, if explained in detail, can look complicated on the surface. Just try to create a flow diagram for something as simple as serving cereal for breakfast. When you factor in all the variables it looks like a process diagram for a nuclear power plant.
There is an excellent and very succinct article on the TomEE Community page titled “Contribution Workflow” which you can use as a reference once you understand the process. If, however, you are new to JIRA, open source, or TomEE there will be some knowledge gaps because that succinct article, “Contribution Workflow”, assumes you know a lot before you even get started.
Section 3: Create a JIRA Account
Before you can use JIRA you need to create a TomEE JIRA account. If you’ve already introduced yourself to the community, as explained in “It’s Easy! Get the TomEE Source Code and Join the Community” then you are off to a good start.
The process of signing up for a JIRA account is pretty self-explanatory. Just go to the Apache JIRA hosting service and create a new account with a username, password, and email address.
Note: When you create your JIRA account I suggest you use the same username and email address you used to introduce yourself on the mailing list and when creating your GitHub account. It can get really confusing when someone uses different identities for the mailing list, GitHub, and JIRA. We want to avoid that if possible.
Once you have created your account and are signed into the Apache JIRA service, you can find the TomEE JIRA instance by pointing your browser at the following link:
You should see a web page that looks similar to the one pictured above. Don’t worry about understanding all the fields in a JIRA ticket. It’s not really necessary, at this point, to know the details. What is important for this article is understanding how creating a JIRA ticket fits into the overall Contribution Workflow. When you are done with this article you can learn more about all the fields in a JIRA ticket by reading the article “It’s Easy! The Anatomy of a JIRA Issue.”
Section 4: The JIRA Ticket Process
The purpose of this first installment of the series on the TomEE Contribution Workflow is to explain this sub-process. Subsquent articles will cover other sub-processes in more detail.
The “JIRA Ticket” part of the Contribution Workflow is where you get started when contributing code or documentation to the TomEE project.
4.1: Getting Started
All the work on TomEE should have a corresponding JIRA ticket, or if it’s an Epic, a corresponding Sub-task. You have essentially three choices when it comes to getting started with a JIRA Issue: You can ask for an existing ticket, find an unassigned open ticket, or you create your own JIRA ticket.
The process is slightly different for each approach, but after a couple of steps, the paths merge into the same decision points. Let’s start by imagining that you are going to work on an exciting JIRA Issue or Sub-task.
Note: As explained in the article “It’s Easy! The Anatomy of a JIRA Issue” an Epic is simply a JIRA ticket with lots of sub-tasks each of which is a JIRA ticket in its own right. When you are working on an Epic you are working on one of the Sub-tasks. If it’s not an Epic, then it’s just a normal JIRA ticket with only one piece of work that needs to be done.
4.2: Requesting a JIRA Issue
One of the best ways to get started is to join the mailing list and ask, “How can I help?” as described in the article, “How to Get Started Contributing to TomEE or any Open Source Project”. Most of the time we maintain a couple of Epics with Sub-tasks (narrowly-scoped JIRA tickets) that are easy for people new to the project to take on. It’s very likely that the email you receive welcoming you to the community will have a link to one or more Epics. Below is an example of the kind of email you may receive.
While we try to line up tasks for people new to the TomEE project, we don’t always keep the pipeline full so if no one sends you any JIRA Issue links, just email back and ask for suggestions or you can go find your own JIRA Issue as discussed in subsections 3.3 and 3.4.
Let’s assume someone does point you to an existing JIRA ticket. Here are the steps you should follow when taking on an issue offered to you.
Let’s look at each step in m more detail.
You: Request an Issue
In this case, you send out an email to the [email protected] mailing list request an issue.
Note: We have contributors all over the world and while everyone will not be awake and at their keyboards when you post messages to the mailing list, someone will respond to your email within 24 hours in most cases. Remember everyone is a volunteer so be patient and the responses will come.
We: Send Issue Links
Assuming someone is available, you should get a reply with some links to suggestions of issues to work on. Follow links directly to the suggested JIRA tickets and decide if any one of them is a good fit.
You: Ask Questions on the Mailing List
When you get suggestions for JIRA Issues, be sure to ask questions on the mailing list if it’s not 100% clear what is needed. Don’t worry about sounding stupid. We’ve all been there and until you have more experience in the project everything is going to feel foreign to you.
If one of the issues seems interesting, take the time to go into the TomEE project and find the files that will be impacted. These might be documents or Java classes or something else. If you cannot find it, ask on the mailing list. Learning the directory structure of the TomEE project is going to take some time so we don’t expect you to know your way around until you’ve been working on the project for a while.
You: Request to be Assigned an Issue
If, after reviewing the suggested JIRA tickets, you feel that you can take one of the issues on, then send an email to the [email protected] mailing list asking for someone to assign it to you. We’ve set up restrictions so that you cannot assign a ticket to yourself. This avoids the problem where people assign themselves JIRA tickets that no one else knows about. Because you have to ask for someone else to assign it to you, you make everyone on the mailing list aware that you are taking that issue on as a task. Transparency and openness is the key to successful open source projects.
At this point, we advance to the last step, “4.5 We: Assign Ticket To You”, in the JIRA Ticket portion of the Workflow. Since that step is shared by all the ways you can get a JIRA ticket, it’s covered and the end of this installment.
4.3: Searching for an Open Issue
There are many issues in the TomEE JIRA system that have been reported but have not been addressed yet. That’s because it’s easier to identify issues than it is to solve them! These “open” tickets are open to anyone who wants to take them on. Assuming you find an “open” ticket that you are comfortable working on, you may want to request to work on that ticket.
- To get started: Go to the TomEE JIRA Issues Page
The process of searching for and selecting a JIRA ticket is pretty straight forward and can be accomplished in just a couple of steps.
You: search for a JIRA Issue
Once you get to the TomEE JIRA site, you should see a web page that looks like the one pictured earlier. This lists all of the JIRA issues being tracked by the system. By default, the “Open” issues are listed in order of priority with the most pressing issues at the top. That is the default setting, but if JIRA is not displaying open Issues you can change the filter above the Issue list so that it will. Just click on the link “Switch Filter” and select “Open” as shown in the screenshot below.
Take the time to look over the tickets in detail. There is a lot of information there. Of particular importance is that the issue is “Open” and that it is “Unassigned”. We are already filtering for “Open” so that should be a given. To tell if an issue is “Unassigned” you just need to look at the “Assignee” field as highlighted below.
- Check that the “Assignee” Field is “Unassigned”
Once you have established that the ticket is both “Open” and “Unassigned” you should review the description located just below the details section (see above).
- Review the Description
If you think you can handle the ticket, you can request to have it assigned to you.
Note: There really is a lot of valuable information on a JIRA ticket and the volume of information can be a bit overwhelming and intimidating at first, but once you understand what all those fields stand for it’s really pretty easy. If you want to know more about a JIRA ticket and its fields read “It’s Easy: The Anatomy of a JIRA Issue” which will give a detailed explanation of tickets and searching.
You: Ask Questions on the Mailing List
Remember in the TomEE project, “there are no stupid questions.” As I said before, we get it. You are new to the project and possibly JIRA, GitHub, and open source in general, so getting started can feel like drinking from a firehose. Just remember, it’s a process that can be learned. You already know how to code in Java so you are at least 75% of the way to success.
You want to find out as much as possible about the ticket before you decide to take it on, so ask questions about it. It also helps to know where the code or documentation in question is located, so if you can’t find it on your own, ask about that as well. If you are not getting enough feedback ask the person who reported the Issue in the first place (that person is identified in the “Reporter” field right next to to the “Assignee” field on the JIRA ticket). Chances are that the “Reporter” knows the most about the issue since they discovered it.
You: Request to be Assigned an Issue
When you find a JIRA ticket that interests you, just ask on the mailing list if someone could please assign you that issue. Make sure you list the Issue identifier (e.g. TOMEE – 2457) in the subject line. Someone will either say, “Yes” take it on and assign you that issue or “No” for some good reason. The reason that someone might say, “No”, has nothing to do with your competence and everything to do with priority and context of the issue, so don’t take a rejection personally. If this isn’t right for you there are plenty of other issues to choose from.
At this point, we advance to the last step, “4.5 We: Assign Ticket To You”, in the JIRA Ticket part of the Workflow. Since that step is shared by all the ways you can get a JIRA ticket, it’s covered and the end of this installment.
4.4: Discovering a JIRA Issue
It’s not unusual for people new to the project to find their own work. In fact, any contributor can create a JIRA ticket. If being assigned an issue is not for you or if you just want to find your own work then follow these steps.
Let’s take a more detailed look at the steps for creating and getting assigned your own JIRA ticket.
You: Discover a Bug / Enhancement
As you get more familiar with the documentation and the code-base, you’ll probably see areas for improvement (we can always make TomEE better), spot a bug, or tests that are needed. That’s kind of the whole point of open source, beyond the “free” part: more eyes on the code results in better code. When you see issues, you may not have time to address them, but you can take a few minutes to follow these steps to see if a JIRA ticket is needed.
You: Search for a Related Issue
Sometimes you’ll discover something that is already captured in a JIRA ticket which may be open or being worked on by someone else. When this happens you can look for another task or ask to be assigned the ticket if its “Unassigned” and is “Open”. If you decide to look for something else, check to see if you can add any helpful comments to the JIRA ticket before moving on. If you decide you would like to take on the ticket than pick up the processes at steps 3 & 4 of the section “3.3 Searching for an Open Issue”.
You: Ask Questions on the Mailing List
It’s always good to test the waters on the mailing list before moving forward with the next step which is to create a JIRA ticket. Frequently the problem will be familiar to someone but is undocumented or there may have been a JIRA ticket that was created that you missed in your search. Other times, the problem will be new to everyone in the community in which case creating a JIRA ticket for the issue is the next best step.
You: Create A JIRA Ticket
To create a JIRA ticket log-in to the TomEE JIRA system.
- Go to the TomEE JIRA instance and log in.
- Click on the “Create” button at the top of the page.
The first thing you will see is the “Create Issue” dialog box. You want to make sure that the “Project” is set to “TomEE (TOMEE”) as indicated by the green arrow.
- Check to make sure that “TomEE (TOMEE)” is selected in the “Project” field.
Second, you are going to select the “Issue Type”. There are many different issue types and the meaning of each type is fairly self-explanatory, but a detailed discussion of each type can be found here in the article “It’s Easy: The Anatomy of a JIRA Issue”.
- Select the appropriate Issue Type
Next, you are going to add a one-line summary of the problem which will act as the title of the issue. This should be explicit yet succinct so that it’s easy to read from the JIRA Issue list (see the green arrow below).
You will also want to select the priority of the issue. If it’s a bug the priority maybe pretty high, but if it’s an issue that is not breaking the build and does not cause problems at runtime, select a lower priority until you are sure of the severity.
- Enter a one-line succinct explicit summary
- Select the appropriate Priority
In many cases, you will not need to fill out the Component and Version fields, but if you feel these are appropriate you can learn all about them in here in the “It’s Easy: The Anatomy of a JIRA Issue” article.
Finally, you want to fill in the description. It’s important that you provide as much detail as you can at the time you create the ticket. However, you may discover more information about the issue as you work on it in which case you can add more information to the details section later.
- Fill out the description field with as much information as you can.
Once you have done that and edited any other fields you that are appropriate, click the “Create” button (see orange arrow above).
- Click on the “Create” button
When I did this for the first time I was confused because the JIRA ticket I had just created didn’t show up on the JIRA Issue list. It turns out that the issue is added into the list of JIRA issues according to its status, priority, and issue type. You’ll want to find the issue you just created and to do so you use the “Switch filter” dropdown box and select “Reported by me”.
- Click on “Switch Filter” and select “Reported by me”
You: Request to be Assigned Ticket
Finally, if you want to work on the ticket you just created, send a message to the [email protected] mailing list requesting that someone assign the issue to you. Put the ticket identifier and summary (title) in the subject line. Note, you cannot assign an issue to yourself. Someone else has to do it.
- Copy the ticket Identifier and summary and send an email asking to be assigned the issue.
4.5: We: Assign a Ticket to You
Whether you request a JIRA ticket, find one, or create one, the last step in the JIRA Ticket process is to have the ticket assigned to you. Remember, you cannot assign a JIRA ticket to yourself.
The people who assign JIRA tickets are a small subpopulation of the community and it’s their job to ensure that there is no duplication of effort and that Contributors are assigned tickets with which they can be successful.
Most of the time, if you have chosen a ticket with a level of complexity that matches your experience on TomEE, you’ll be assigned the ticket without question. It might take a couple of days as your request is reviewed but once it’s assigned to you, you will get an email from JIRA telling you so. If, however, you do not hear back, check the ticket itself and see if your name in listed next to the “Assignee” field. If it’s not, and no response has been given to your original request, feel free to ping the [email protected] email list again and ask for some help.
What’s Next?
This article has provided you a solid foundation for finding work to do on TomEE and getting assigned a JIRA ticket. But the JIRA Ticket process is just the start. Next, you get to work on the actual problem and do some real coding or document writing, which is, after all, the reason you are here right? We’ll cover that aspect of open source, Process Task, in a future edition of “It’s Easy!”
