Introduction

To minimize both confusion among JIRA users and administrative overhead, SIS projects will be configured in JIRA according to standard patterns described in this document and documents to which this one is linked.

Context-setting sections of this document are followed by quick checklists of information a project lead needs to provide to JIRA administrators in order to set up a new project, associate users with a project by assigning them project-specific roles, and/or to add new users to the IS&T JIRA instance. A table of contents is included at the top of this page.

Vendor documentation on JIRA can be found here. Refer to the documentation for the currently-installed version of JIRA. As of April 2006, IS&T is running JIRA version 3.5.3, for which documentation can be found here. Most questions regarding use of JIRA can be resolved most efficiently by consulting the documentation; this is a good place to start.

Overview of JIRA Project Configuration

Project Permissions govern who can read, add to, or modify issues in a given JIRA project. Issue-Level Security can be used to narrow those permissions further. Permissions are generally granted to groups of JIRA users, such as "dbas" or "bearfacts-customers."

Notification schemes govern who receives e-mail from the JIRA system when different activity occurs on an issue.

Workflow is "the set of stages and stage transitions that an issue goes through in its lifecycle" - that is, a logical, sequential progression of statuses such as "Open" - "In Progress" - "Implemented" - "Verified" - "Resolved" - "Closed."

Project Permissions and Issue-Level Security

Project-level permissions are based on a template modified in a standard way for each individual project (or groups of projects that require identical project-level permissions). An example of the template modified for the "breez" project can be viewed here; another view of the permissions that might be easier to understand is here. In considering the template example, you can transpose it to your project by substituting your project's name for "breez" when reading the project-specific groups (in the example they are breez-leads, breez-developers, breez-customers). In the standard template, only the project-specific groups (*-leads, *-developers, and *-customers) vary. The other groups are always included as in the example. Note that project permissions are the broadest permissions that can be granted on an issue in the project.

The permissions on an issue may be narrowed from the project-level permissions described above. If desired, a project may be configured to apply a narrower issue-level security configuration by default to each new issue upon its creation; in any case, a user may modify the issue-level security for issues in a project for which s/he has "Edit Issues" permission (e.g., the *-leads group is granted permission to perform this operation). A set of standard security levels for issues is created when the project-level permissions are set up. Like project-level permissions, these are modified in a standard way, from a template. The standard issue-level security choices are shown here for "breez." Again, simply substitute "breez" in the example with a different name to see how the example will apply to another project.

Notifications via E-mail

JIRA sends e-mail notifications to users when activity occurs on an issue. Projects may be configured such that JIRA sends more or less e-mail; it may be appropriate to alter the level of notification based on the level of activity going on in a project. Project leads may specify any of three standard notification schemes, and may request of a JIRA administrator that the notification scheme associated with a project be changed, as necessary/desired.

Notification Schemes are shared among all projects - there are no project-specific notification schemes. The standard schemes generate e-mail as shown in these representations of the Notification Schemes as they are visible to JIRA administrators:

• Verbose Notification Scheme
• Standard Notification Scheme
• Terse Notification Scheme

In reviewing the above document, be sure to understand the special "Project Lead" role, described here.

Workflow: issue lifecycle

JIRA workflow is described in the Atlassian documentation, here (you will likely be interested only in the "Steps and Transitions" section of the linked page).

Projects share the same workflow, but it is up to the project participants which workflow steps and transitions are actually utilized.

The standard SIS project workflow may be viewed here. The brief description of JIRA workflow linked above will be very useful in deciphering this document!

It is also important to understand that certain workflow transitions may only be initiated by certain users, generally based on a role (e.g., may be initiated by the Current Assignee) or a permission (e.g., must have "Resolve Issues" permission to initiate). In the standard workflow, the following permissions apply to the listed transitions:

• Start Progress: Current Assignee (role)
• Stop Progress: Current Assignee (role)
• Ready to Verify: Current Assignee (role)
• Reopen Issue: Resolve Issues (permission)
• Request migration to Dev: Resolve Issues (permission)
• Migrate to Dev: Resolve Issues (permission)
• Request migration to QA: Resolve Issues (permission)
• Migrate to QA: Resolve Issues (permission)
• Verify resolution: Current Assignee (role)
• Request migration to production: Close Issues (permission)
• Resolve Issue: Resolve Issues (permission)
• Close Issue: Resolve Issues or Close Issues (permissions)

Creating new JIRA projects

To set up a new JIRA project, a JIRA administrator needs the following information from an appropriately authorized staff member:

• Name of project
• Suggested 3-letter abbreviation for project
• URL associated with project (project or application site); this is optional
• Project Lead
  • a single person who will be the default assignee for new issues; or,
  • a list of multiple persons who will be subscribed to a project-specific mailing list associated with a "placeholder" JIRA account; if this option is chosen, this account will be the default assignee for new issues in this case, and someone on the mailing list should be responsible for timely reassignment to a "real" team member
  • cf. here for more info on the Project Lead role
• A short project description
• Choice of verbose, standard, or terse/quiescent Notification Scheme (cf. here for more info)
• Choice of default Issue-Level Security (will narrow standard project security); cf. here for more info

Associating JIRA users with project-specific groups

• For folks who don't yet have JIRA logins, see Adding new JIRA users, below
• In general, users associated with projects may be assigned to any of three groups:
  1. myProject-customers
  2. myProject-developers
  3. myProject-leads
• The appropriate project lead needs to tell the JIRA administrator which individuals are to be assigned which project-specific roles
• Assignment of roles affects the user's permissions within a project; cf. here for more info.
• Users assigned to the leads group are also assigned to the developer group; thus, leads group members have both leads' and developers' permissions.

Adding new JIRA users

• To create a new user in JIRA, the JIRA administrator needs:
  1. the user's full name
  2. the user's e-mail address, preferably the one listed in the Cal Directory
• The user's e-mail address (the part before the @) is generally used as the person's JIRA login
• The JIRA administrator will assign a password that the user is expected to change
• JIRA automatically generates an e-mail to the user with the JIRA URL, and the user's login id and password.
• The JIRA administrator makes all new users members of the jira-users group. Other groups, such as jira-project-leads, jira-developers, jira-customers, sis-leads, sis-customers, and sis-developers are assigned as appropriate.

About Leads groups vs. "Project Lead" role

Each project has a project-specific leads group (e.g., "breez-leads"). This allows multiple individuals to share responsibility for the tasks a project lead may perform in JIRA, per the "Permission Scheme" (described above). There is no requirement that there be multiple members of the leads group.

Each project also has a similarly named role called "Project Lead." This role corresponds to exactly one JIRA user; it is not a group of users. The "Project Lead" is always the default assignee for a new issue. Also, the "Project Lead" is notified of activity on an issue via the "Notification Schemes" described above. A user who has "Assignable User" permission must be assigned the "Project Lead" role; it is generally a very good idea to assign a user - presumably someone in the project *-leads group - who also has the "Assign Issues" permission.

If requested, the "Project Lead" role may be assigned to a "placeholder" account, not associated with a person who actually logs in to JIRA. The e-mail address for this placeholder account will be a list maintained outside of JIRA, by the JIRA administrator. This option is useful if multiple individuals ought to receive e-mail upon issue creation and default assignment of an issue.