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

First Steps

Access the Apache Jira dashboard and read the introduction to see what permissions are available to users, and to create an account. Note that only developers on a project have full permissions for modifying issues. To get this permission, email the dev@ mailing list to introduce yourself and to be added as a contributor in the Beam issue tracker including your ASF Jira Username. For example this welcome email.

Navigating Jira

The Apache Jira is used for many Apache projects, not just Beam. The Projects menu on the top bar lets you select a project to browse and see what project you are currently browsing. To find Beam, use that menu and select View All Projects, then search for Beam.

All Jira issues are identified with a unique ID. All Beam issues begin that ID with the key BEAM to differentiate it from issues in other projects. These IDs are used to refer to Jira issues within Beam's github repo and source code as well. (Example: BEAM-1234)

Searches and Filters

When searching for issues the default search page includes all issues and projects. To narrow this search down, select from filters near the top of the search. This allows you to narrow the search down to only Beam issues, among other criteria. 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 use them, select the dropdown menu titled More, and then select the criteria you are looking for, and it will be added to the list of criteria you can use to filter.

Pressing the Save As button on the top of the page allows you 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 that can be used when creating an issue, but will instead clarify any commonly-used fields that may be unintuitive for a first-time user, as well as cover any Beam-specific details.

Issue Type

This field lists what type of issue is being created. The most import are "Bug" if you found a bug and "New Feature" if you are recording a feature request. Use the question mark button next to the drop-down to view the list of 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

This field lists the priority of the issue being created. Like with issue type, use the question mark button next to the drop-down to view the list of descriptions for all priorities.

Priority is vague, and can mean different things depending on issue type. Beam uses 5 levels of severity; they may correspond to "P0" through "P4" in other systems. You can think of them like this:

• P0 Blocker: get paged, stop whatever you planned on doing, work late to fix
• P1 Critical: continually update everyone on status and shouldn't sit around unassigned
• P2 Major: most things here; they are important 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 roadmapping but still useful if someone wants to do it
• P4 Trivial: a special category for typos or minor cleanups that might be good for newcomers just to get started with the project, build system, etc

Components

A list of all Beam components and their descriptions can be found in the components page for the project. These components correspond to different areas within the Beam project and all issues should be filed 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 that are not directly related to code. Beam has a few labels that are used systematically:

• starter - means that it is a good task to get started contributing to Beam.
• triaged - means that an experienced member of the community has reviewed the component, priority, 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 - means that the Jira is about a test that was disabled because it was broken, and it should be fixed and re-enabled
• flake - means the Jira is about a test that is flaky so it harms everyone's productivity, a non-sickbayed flake must always be 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 too much consistency should not be expected.