JIRA Projects: Standard Setup for IS&T

To avert confusion among JIRA users and minimize administrative overhead, IS&T projects will be configured in the IS&T instance of JIRA (at https://beartracks.berkeley.edu/jira) according to standard patterns described in this document and documents to which this one is linked. Exceptions are possible, but are discouraged unless the standard setup conflicts with significant business needs.

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.

This local document is NOT meant to replace vendor documentation, which can be found on the Atlassian.com site. Refer to documentation for the currently-installed version of JIRA. As of November 2007, IS&T is running JIRA version 3.10, for which documentation can be found at http://atlassian.com/software/jira/docs/v3.10/.

Most questions regarding use of JIRA can be resolved most efficiently by consulting the vendor documentation; the JIRA Concepts - Issues page is a good place to start.

Project and issue administration that can be performed by project leads (without need for intervention by a JIRA administrator) is available from the Administer Project link on each Browse Project screen; and from the Edit this issue link available when viewing an individual issue (a user may see these links or not depending on her/his permissions for a given project).

The configuration options described in this document are those that require a JIRA administrator to configure. A summary follows:

Project Permissions govern who can read, add to, and otherwise modify issues in a given JIRA project. Closely related projects can conveniently use a single Permission Scheme. Issue-Level Security can be used to narrow Project Permissions on an issue-by-issue basis. Permissions are generally granted to groups of JIRA users, such as "dbas", "myproject-developers" or "myproject-customers."

Notification schemes govern who receives e-mail from the JIRA system when different activity occurs on an issue (e.g., when an issue is added, commented-on, resolved, or closed).

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-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). Project permissions for a sample IST-AS project are displayed in two ways - by permission, and by groups to whom permissions are granted - in the linked JIRA Permissions page. In considering the template example:

• Transpose the example to your project by substituting your project's name for "myproject" when reading the project-specific groups (in the example they are myproject-leads, myproject-developers, myproject-customers).
• In the standard IST-AS template, only the project-specific groups (*-leads, *-developers, and *-customers) vary.
• For IST-AS projects, groups that are not project-specific are always included as in the example. For projects outside IST-AS, the only difference is that the ist-as-project-browsers group is excluded.
• 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. This is done by configuring a project to allow application of narrower issue-level security.

• A project may be configured to apply issue-level security to each new issue upon its creation.
• 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 in the standard project permission scheme).
• 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.
• Standard issue-level security choices are shown in this illustration, for the Streek project; to transpose to your project, substitute "myproject-leads" for "streek-leads", etc.

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. Project-specific notification schemes are discouraged, except when significant business needs require otherwise. 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 linked documents, be sure to understand the special "Project Lead" role, described About the Project Lead section, below.

JIRA workflow is described in the vendor's Workflow Steps and Transitions documentation.

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

Three workflows are available for use by IST; most use the first workflow listed. The brief description of JIRA workflow linked above will be very useful in deciphering the following workflow representations! The available workflows are:

• IST Standard Project Workflow (v 1.0.1)
• IST Migration Workflow
• Default JIRA workflow [links to vendor site]

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 IST Standard Project 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: Close Issues (permission)

Other workflows are similarly constrained.

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 JIRA user who will be the default assignee for new issues; or,
  • the list address (e.g., myproject@lists.berkeley.edu) that can be associated with a "placeholder" JIRA account.
    
    • If this option is chosen, the placeholder account will be the default assignee for new issues in this project, and someone on the mailing list must reassign issues to an individual team member
    • For more information on creating a list at UC Berkeley, consult How do I create a Majordomo mailing List? in the IST Knowledge Base.
  • Cf. About the Project Lead role, below, for more info on that role
• A short project description
• Choice of verbose, standard, or terse Notification Scheme; cf. Notifications via E-mail, above, for more info
• Choice of default Issue-Level Security, if any (will narrow standard project security); cf. Project Permissions and Issue-Level Security, above, for more info

• If individuals who don't yet have JIRA logins need access to your JIRA project, 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. Project Permissions and Issue-Level Security, above, for more info.
• In a project with standard permissions, users assigned to the leads group are also assigned to the developer group; leads group members therefore have both leads' and developers' permissions.

• 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 temporary a password that the user is expected to change upon reciept.
• 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, etc. are assigned as appropriate.
• A new user needs to be associated with specific project roles before s/he can do anything interesting in IST's JIRA instance. Cf. Associating JIRA users with project-specific groups, above, for more info.

Each project has a project-specific leads group (e.g., "myproject-leads"). This allows multiple individuals to share responsibility for the tasks a project lead may perform in JIRA, per the "Permission Scheme" associated with a project (cf. Project Permissions and Issue-Level Security, above). The leads group may have one or multiple members.

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" associated with a project (cf. Notifications via E-mail, above). A user who has "Assignable User" and "Assign Issues" permissions is an appropriate candidate for the "Project Lead" role; this is almost invariably someone in the project's leads group (e.g., myproject-leads).

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 should be a list maintained outside of JIRA, by one or more project members. This option is useful if multiple individuals ought to receive e-mail upon issue creation and default assignment of an issue (cf. Creating new JIRA projects for more on this option).