NOTE: Beam no longer uses Jira for issue tracking. Instead, please see https://beam.apache.org/contribute/ for information on getting started with GitHub Issues. Jira may still be needed to interact with other Apache projects or Infra, but will not be needed for most contributors.

This guide aims to introduce Beam contributors to the basics of using the Apache Jira.

How to get started on Jira

To start collaboration in the Apache Jira:

1. Access the Apache Jira dashboard.

2. Read the introduction to see what permissions are available to users and to create an account. 
   

   Only developers on a project have full permissions for modifying issues. 

How to navigate Jira

The Apache Jira is used for many Apache projects. To navigate in the Beam specific (legacy) issues:

1. Go to https://issues.apache.org/jira
2. On the top bar, select the Projects > View All Projects to browse and see what project you are currently browsing.
3. Search for "Beam" and select Beam.

Searches and Filters

Commonly used filters for Beam include Project, Status, Component, and Label. Some of these filters may not be visible by default in the Basic view. To view all issues or create a search:

1. Select View all issues and filters.
2. Select the More dropdown menu.
3. Select the criteria you are looking for, and you can use it in the list of criteria you can use to filter.
4. Select Save as to save a commonly used filter.

Saved filters can be viewed by hovering on the left side of the page to reveal the filters menu.

Creating Issues

This guide will not cover every field you can use when creating an issue. Instead, it will clarify any commonly-used fields that may be unintuitive for a first-time user and include any Beam-specific details.

Issue Type field 

This field lists what type of issue you are creating. The most important are:

• Bug. If you found a bug that needs to be fixed.
• New Feature. If you are recording a feature request which has yet to be developed.

Click the icon to view the descriptions for all issue types. There are no particular rules about when to use other types. If you are unsure, stick to Bug or New Feature. Someone from the Beam community will check the details anyhow.

Priority field

This field lists the priority of the issue you are creating. The Priority is vague and can mean different things depending on the Issue Type. Beam uses five levels of severity; they may correspond to "P0" through "P4" in other systems. Think of them like this:

• P0 Blocker. Get paged, stop whatever you planned on doing, work late to fix it.
• P1 Critical. Continually update everyone on the status and shouldn't sit around unassigned.
• P2 Major. Most things here are necessary but not an interrupt - if unsure, use Major, and someone from the community will review the details.
• P3 Minor. Nice-to-have things may not make it onto regular planning and road mapping but still useful if someone wants to do it.
• P4 Trivial: a particular category for typos or minor cleanups that might be good for newcomers just to get started with the project or build system.

Click the icon to view the descriptions for all issue types.

Component/s

You can find a list of all Beam components and their descriptions on the

Components page of the project. These components correspond to different areas within the Beam project, and you should file all issues in one or more relevant components. For this reason, contributors should review the components page and have a basic familiarity with the components of the project.

Labels

A label is an arbitrary text string attached to an issue. Labels are used to tag issues for searches and are usually used to identify aspects of an issue not directly related to code. Beam has and uses a few labels systematically:

• starter.  This label means that it is an excellent task to get started contributing to Beam.

• triaged. This label means that an experienced member of the community has reviewed the component, priority, and issue type; and that someone who understands the issue has been contacted.  

  Do not add this label to new issues or no one will look at it.

• sickbay. This label means that the Jira is about a test that was disabled because it was broken, and it should be fixed and re-enabled.
• flake. This label means the Jira is about a flaky test, so it harms everyone's productivity. A non-sickbay flake must always be a Critical priority or higher.

Contributors are encouraged to label issues in whatever other ways they want. However, there are no expectations or requirements regarding labels, so don't expect too much consistency.