jira guidelines for customers - intracom-it.dk guidelines for customers.pdf · jira the name comes...

Intrasoft/CS/Process/DOC001/v2.2/2013.01.11

Copyright Intrasoft International Scandinavia

ESKORT JIRA Guidelines for Customers

ESKORT

JIRA Guidelines for Customers

Intrasoft/CS/Process/DOC001/v2.2/2013.01.11 i (ii)


DOCUMENT

Title: JIRA Guidelines for Customers

Document: Intrasoft/CS/Process/DOC001

Date: 2013.01.11

Version: 2.2

Author: Jørgen Rune Mortensen

Contributions by: Michael Suodenjoki, Robert Mérineau

Distribution: Customers (JIRA users)

Versions: 1.0 Initial version

2.0 Updated for JIRA 5.2.

2.1 Updated with Intrasoft name, added section about workflow status etc.

2.2 Updated with syntax highlighter description inWIKI editor and cleanup of layout etc.

Printed: 2013.01.11

ESKORT


Intrasoft/CS/Process/DOC001/v2.2/2013.01.11 ii (ii)


Table of Contents

1. Introduction .......................................................................................... 1

1.1 Purpose ..........................................................................................................................1 1.2 Contents .........................................................................................................................1 1.3 Application ....................................................................................................................1 1.4 Terminology...................................................................................................................1

2. Project and Product concepts ............................................................ 2

2.1 Versions .........................................................................................................................2 2.2 Components ...................................................................................................................2

3. Working with JIRA ............................................................................... 3

3.1 Accessing JIRA ..............................................................................................................4 3.2 Reporting (creating) an issue .........................................................................................5

3.2.1 Issue type ...................................................................................................................5 3.2.2 Requirements to the information .................................................................................6 3.2.3 One issue per JIRA item .............................................................................................8 3.2.4 Issue redundancy ........................................................................................................8

3.3 Adding comments, screenshots and data files to an issue ...............................................9 3.4 Watching issues and how to add/remove yourself as watcher .........................................9 3.5 Testing an issue ........................................................................................................... 10 3.6 Processing change requests ......................................................................................... 10

3.6.1 Analysis ................................................................................................................... 11 3.6.2 Design ...................................................................................................................... 11 3.6.3 Approval .................................................................................................................. 11 3.6.4 Implementation ........................................................................................................ 11 3.6.5 Test .......................................................................................................................... 11

3.7 WIKI Editor ................................................................................................................. 11

4. Workflow status ................................................................................. 14

4.1 Open status (Action Intrasoft) ...................................................................................... 15 4.2 Pending status (Action for the customer) ..................................................................... 15 4.3 In Progress status (Action Intrasoft) ............................................................................ 15 4.4 In Test status (Action for the customer) ....................................................................... 15 4.5 Test Approved status (Action Intrasoft) ........................................................................ 16 4.6 Test Rejected status (Action Intrasoft) ......................................................................... 16 4.7 Resolved status ............................................................................................................. 16 4.8 Closed status ................................................................................................................ 16 4.9 Reopened status ........................................................................................................... 17

°

ESKORT


Intrasoft/CS/Process/DOC001/v2.2/2013.01.11 1 (17)


1. Introduction

1.1 Purpose

The purpose of this document is to constitute the formal process of how you (the customer)

and Intrasoft International Scandinavia A/S (hereafter Intrasoft) exchange information in

connection with JIRA issues, and JIRA incident reports in context of a customer project.

1.2 Contents

The document contains a description of the basic concepts as well as a definition of the most used terms.

The document also contains a step-by-step description of how the customer is intended to

report errors, issues, make change requests and how the customer through JIRA can monitor the progress of issues.

1.3 Application

The document is written with the customer as recipient but is applicable for the following

two groups:

Customer: The customer personnel who reports errors and raises issues in context of an Intrasoft project.

Intrasoft: The Intrasoft Compliance Solution personnel who processes the issues (in

level of technical as well as project management).

1.4 Terminology

This section defines the most common terms used within this document.

Change Request An issue in JIRA that deals with a request for a change in the

functionality of a component.

Issue Common entry for an Incident report or Issue in JIRA.

JIRA The name comes from the original Japanese name for Godzilla,

"Gojira"[1][2]. The developers of JIRA wanted something related to

Bugzilla, and so they came up with Gojira. JIRA is therefore not an acronym.

JIRA Incident report An issue in JIRA that deals with an observed error incident, i.e. a

problem within an existing component.

JIRA Issue An issue in JIRA that deals with a subject that is not directly an error

incident (e.g. a question, change request or feature requirement).

JIRA Project A project in JIRA. It is identified with a unique short code (typically a

three to five character letter code). One JIRA project can relate to one customer project or to one ESKORT product.

http://en.wikipedia.org/wiki/Godzilla

http://www.imdb.com/title/tt0047034/

http://www.imdb.com/title/tt0047034/

http://en.wikipedia.org/wiki/Bugzilla

http://en.wikipedia.org/wiki/Acronym

ESKORT




2. Project and Product concepts

Intrasoft offers a wide range of ESKORT products for the compliance domain within the

taxation and customs authorities. The systems provided to you are typically one or more of

the ESKORT products customized and localized to match your specific environment and requirements.

The customization, localization and requested changes are made in context of what is

defined as a customer project.

A customer project is defined as changes made to one or more ESKORT products to make

the product fit into the environment and to comply with specific customer requirements.

In general each customer specific project is registered as one JIRA project.

2.1 Versions

Customer project specific changes are typically delivered to you as a patch to the ESKORT product, i.e. first the ESKORT products are installed followed by the installation of your

project specific patches. To make each patch capable of working together with the

ESKORT product each project specific patch must be associated with a specific version of the ESKORT product. The versions will be defined in the release notes contained in each

delivery.

In the customer specific JIRA project the delivered versions and planned, future versions

are created along with the relevant versions of the associated ESKORT product. Hereby it is possible to register issues to specific versions as well as to plan the release of each

resolution.

2.2 Components

Each ESKORT system is divided into components each performing a well-defined functionality. The components are described in the documentation of the specific ESKORT

product. If a component is developed for a customer specific purpose it will be described in

the project specific documentation.

In the customer specific JIRA project the components are registered. Hereby it is possible to register issues to specific components.

ESKORT




3. Working with JIRA

JIRA is a web-based, issue tracking application. The following URL gives access to

Intrasoft JIRA:

https://jira.intracom-it.dk

One or more JIRA accounts are provided for a customer organization, one for each

customer user, through which the users will be able to logon to JIRA to create issues or

incident reports, comment existing issues, transition issues through the workflow, as well as watch the state of issues registered for your projects (see section 3.1).

INFO: In JIRA a user is authenticated by a username and password.

This chapter describes how you and your project team can work with JIRA. A more

detailed User Guide to JIRA can be found online by selecting the “Online Help” link provided by clicking on the down arrow at the right of your name in the upper-right part of

the JIRA window.

Figure 1: Illustrates how to access the Online Help.

You should use JIRA when you:

Observe an error incident in your system that you would like to report to Intrasoft.

Would like to raise an issue concerning your ESKORT project or the ESKORT

product provided – this also covers change requests.

When you want to add comments to an existing issue.

The following sections provide the guidelines for how to use JIRA in the process.

https://jira.intracom-it.dk/

ESKORT




3.1 Accessing JIRA

When activating https://jira.intracom-it.dk, the following log in screen appears:

Figure 2: Intrasoft JIRA Log In.

First time you login to JIRA you should change your password to a password that is known only by you. You can change your password by accessing your Profile and activate the

Change Password operation (see figure below).

Figure 3: Illustrates how to access the Change Password window.

Each user account is associated with an email address. JIRA will automatically notify users by sending an email

1 when something happens to an issue. The email is send:

1. to the user that has reported/registered the issue.

2. to the user that is assigned to the issue.

3. to any user that is watching the issue, see section 3.4.

1 Note however that some bulk operations in JIRA executed typically by the project lead can update issues without you being notified via email. This is to limit the amount of received emails.

https://jira.intracom-it.dk/

ESKORT




3.2 Reporting (creating) an issue

This section is a description of the actions you need to take when you are reporting an issue. You can report or register a JIRA item (incident report, issue or change request) by

Type a “c” (unless you are already typing in a field) while the JIRA browser

window is active, or

Click the down arrow on the right of the “Issues” on the text bar and then click on

the “Create Issue” link (see Figure 4), or

Figure 4: Illustrates the process of creating a new issue. You should specify the issue type.

Click the “Create Issue” on the text bar, or by clicking an issue type when

browsing a project (see Figure 5)

Figure 5: Illustrates the process of creating a new issue. You should specify the issue type.

3.2.1 Issue type

Three types of issues are defined, i.e.:

Incident Reports

Issues

Change Requests

The issue types are described in the following sections.

Incident Reports

If you observe a problem that you believe is an error incident (a bug or

malfunction) in the system, then you should create a JIRA issue and set the issue

type to Incident Report.

ESKORT




Change Requests

In you find the functionality of the ESKORT product limited or the specified product is insufficient to meet your needs, you should raise a change request. A

Change Request is a JIRA issue that you create in your JIRA project and which

initiates a new functionality in the system.

Issues

If you have questions to behavior or in general have problems about the system and

are in doubt about whether it is a bug or change request, then simply create an Issue.

In JIRA the difference between a JIRA incident report and a JIRA issue is the existence of

six fields2. Even though this is a small difference the decision of whether an issue or an

incident report should be reported is quite important. To decide whether a JIRA incident

report or a JIRA issue should be reported the following rule of thumb can be used:

You create an Incident Report if you observe an incident you think is an error and you able to refer to a particular section in the specification or the test case that defines the

behavior from which your observation deviates.

If you have a question or need clarifications or think that the specification is unclear

and request a clarification then create a JIRA Issue.

NOTE: In some cases the project lead may update the reported issue to the correct

issue type.

3.2.2 Requirements to the information

When creating an issue it must be filled out properly. If Intrasoft consider an issue to

contain incomplete information it can be rejected and returned.

2 The six fields specific for Incident Report are: Incident Type, Incident Occurrence and Incident Frequency, Path, Verification and Reference.

ESKORT




Figure 6: Create Issue window

The two most important fields are the Summary and the Description fields.

The Summary field is the headline of the issue and will be displayed in JIRA’s lists. For

that reason it is important that you fill the Summary-field with a clear, unique identification

of the issue – do not write “Error found” or “System does not work”. Provide a more precise summary like: “Risk Profile detail print has an empty heading”.

The Description field is where you communicate the more detailed information to the

reader. Write it clearly – let people without too much background knowledge be able to understand the contents. Describe the context so the reader understands in which situation

the issue applies.

The Priority field is set to "Normal" as standard. You can also select Low, High and

Critical. In general, issues that are classified as High or Critical would be of a nature where the system could not be used in production.

The Assignee field: When you create a new issue you can select who the issue should be

assigned to (the assignee). This is selected in the “Assign To”-field. If you are creating an issue for Intrasoft you should leave this field as “- Automatic -“. When Intrasoft is

processing the issue the project lead will decide the assignee.

ESKORT




NOTE: As a result of the process, a JIRA issue changes hands several times and possibly also be returned to you, e.g. if you are asked to test a solution (see

section 3.5 and 3.6.5).

Because several people from your organization can have access to the same projects it is possible for you to use JIRA as your tool for issue tracking and

project management – in fact you can create a JIRA Customer Issue and send

it to one of your colleagues. Thereby issues can stay inside your organization

and never end up at Intrasoft. Intrasoft would like to encourage you to use JIRA for that purpose.

The Attachment field is used to attach files (e.g. documents, text files, screen shots) to the

issue. The system will recognize .jpg file as images and will display them automatically in the Image attachments

Figure 7: Attachment field

NOTE: You can insert more than on file while creating or editing a JIRA issue.

3.2.2.1 When writing Incident Reports

For error incident reports you should write both what you observed and what you expected.

Try to avoid:

Descriptions that make no sense.

Descriptions that do not give enough information.

Descriptions that give wrong information.

Descriptions of problems that turn out to be user error.

Descriptions of problems that turn out to be the fault of somebody else's program.

Descriptions of problems that turn out to be network failures.

In incident reports, try to make very clear what are actual facts ("I was at the computer and

this happened") and what are speculations ("I think the problem might be this"). Leave out speculations if you want to, but do not leave out facts.

See also How to Write a Good Bug Report.

3.2.3 One issue per JIRA item

Keep one issue per JIRA item. Each issue can then be handled separately. If you add more

than one issue per issue, the Intrasoft project lead will either have to split the original JIRA

issue into several issues or reject it. If it later turns out that an issue contained several issues

that should be handled separately it will either be broken into sub-issues or split into several issues.

3.2.4 Issue redundancy

Before you create an issue please make sure that the issue is not already reported. If

Intrasoft receives an issue that is already reported it will be considered redundant and it will

be resolved by the resolution that it is a duplicated issue.

http://www.noverse.com/blog/2012/06/how-to-write-a-good-bug-report/

ESKORT




If you would like to report an issue and have found one similar to your issue it is probably already reported. If you think the issue does not contain exactly the information you would

like maybe you should add a comment to the existing issue instead of creating a new one

(see section 3.3).

3.3 Adding comments, screenshots and data files to an issue

After you have created an issue additional information can be collected that you would like

to add to the issue. In that case, you can add the information as comments to the issue.

In JIRA it is also possible to attach screenshots as images as well as other files (e.g. sample

data files3 which can help reproduce the problem) either when you are editing the issue or

by using an action from the issue display window (see below).

Figure 8: Actions in the Issue Display Windows to Attach Files or Screenshots

3.4 Watching issues and how to add/remove yourself as watcher

For issues that you want to get email notification about changes, you can add yourself as

watcher.

As reporter or assigned user you will pr. default be notified about changes for an issue. If

you have been assigned to an issue and what to follow it after it has been reassigned, then you should add yourself as watcher.

Sometimes the project lead will add you as watcher if s/he consider it relevant for you to

follow the issue.

3 You should properly ensure that you anonymize any data files which contain private data before

attaching them to issues, unless the contents of the data files can be considered as triggers of the issue and important information for finding a solution.

ESKORT




Figure 9: Illustrates adding your self as watcher by clicking on the "Watch" text. The number in

paranthesis indicates how many users are watching the issue. You can also click on the number to

go to the Watchers screen where you can see whom is watching and maintain watchers

(add/remove).

If you get email notifications about issues that you do not want to follow/watch anymore,

then you should remove yourself as watcher.

3.5 Testing an issue

When a fix has been made to an issue, e.g. an error incident, or when a change request has

been implemented, it will be tested in two steps. First Intrasoft will perform a test. If the

test turns out successful the issue will be assigned to you for testing along with the next

release. In that case the state of the issue will be “In Test” until you have tested it and reported the outcome of the test to be either “Test Approved” or “Test Rejected”. The

reporting of the test result must be done in JIRA.

Figure 10: Available actions for an incident report or issue to report the result of customer test.

3.6 Processing change requests

Although it is common for the customers to have a formal approach to handle change

requests, it is possible to use JIRA to register the change requests and to track their status.

When creating a change request, the problems to be solved or the functionality to be added should be described clearly in the Description field and supported by attached documents if

necessary. If you have specific requirements they should also be stated in the description

field. In the description be as specific and detailed as possible so Intrasoft is capable of

understanding your problem and to suggest the best solution.

ESKORT




When you have submitted the change request the state of the issue will be Open. Hereafter the issue will possibly undergo the following phases (the JIRA states are in parenthesis):

1) Analysis (In Progress)

2) Design (In Design)

3) Approval (Design Complete)

4) Implementation (In Progress)

5) Test (Testing)

In the following sections the phases are described.

3.6.1 Analysis

When Intrasoft starts working on the issue the state will change to In Progress. In this state Intrasoft will analyze your problem and requirements and, in collaboration with you,

initiate a process to find the appropriate solution.

3.6.2 Design

In this state (In Design) the solution is being designed and estimated or a fixed price will be

given. When the design has been completed you will be asked to approve it.

3.6.3 Approval

In this state (Design Complete) it is up to you to decide whether implementation of the

change request will solve your initial problem.

In case you think something is missing or misunderstood you must reject it. In that case please provide a clear description of the reason for the rejection. The subsequently process

depends on what you and Intrasoft agree.

In case you agree on the design you must approve it. Hereafter Intrasoft will start the implementation of the change request according to the design.

3.6.4 Implementation

As long as the change request is being implemented and tested at Intrasoft the issue remains in one of the states: In Progress, In Test (Intrasoft), Test Approved (Intrasoft)or Test

Rejected (Intrasoft). When the change request has been implemented and all Intrasoft tests

have verified the implemented functionality the issue will be released and it is the responsibility of you to do the final test.

3.6.5 Test

In the Testing state you are doing the final test of the implementation of the change request. The outcome of your test can be either that the test fails or succeeds.

If you agree that the implementation fulfills the requirements the test result should be OK.

If you find that some requirements are not fulfilled in the implementation the test should fail. In that situation you must provide a very clear description of the reason for your

rejection.

The further work on the change request depends on outcome of the test.

3.7 WIKI Editor

Fields where the icon appear (below on the left) allow the user to markup text, create tables in the field, create links, insert image (jpg files attached to the issue) in the text as

thumbnail or full size etc.

ESKORT




By clicking on the icon, you will toggle the display of the field where you will either “see the markup and plain text” or “see what will be displayed” when the issue is saved.

Figure 11: Description Field (WIKI editor)

By clicking on the Help icon (yellow question mark), JIRA will display a list of the available WIKI markups and functions (see figure below).

Figure 12: WIKI editor on-line help

The WIKI editor also support formatting syntax from text files of different formats, e.g.

xml files or even programming language files. It also supports highlighting specific lines in

the snippets, which is handy if you want to focus the reader to specific lines.

For more see JIRA Syntax Highlighter Plugin

https://bitbucket.org/hski/syntaxplugin-public/wiki/Home

ESKORT




Example: Below is a small example showing a snippet from a file using the {code} formatting – here specifying XML formatted syntax.

Figure 13:Above: Illustrates the WIKI editor to insert {code} parts which highlighted rows. Note

that xml is specified as format and that row 3 is wanted to be highlighted. In next figure you can see

the final result.

Figure 14:Above: Illustrates a preview of the comment showing the final result of the inserted WIKI

code. Note that row 3 is highlighted.

ESKORT




4. Workflow status

The following table lists the status that are of interest for the implementation and/or

maintenance phase of the project:

Status Details

Open The issue has been created.

Pending The issue is pending clarification or action from customer or partner.

Qualified The issue has been qualified by the Intrasoft PM or Project lead and is ready for the assignee to start work on

it.

In Progress This issue is being worked on by the assignee.

In Test The issue is ready for test by the customer.

Test Approved The issue has been tested and the issue is considered resolved by customer.

Test Rejected The issue has been tested and cannot be approved by the customer.

Resolved A resolution has been taken, and it is awaiting verification. From here issues are either reopened, or are

closed.

Closed The issue is considered finished, either because an error has been fixed satisfactorily or a question / request has

been answered or a change has been implemented and tested.

Closed JIRA issues can be reopened.

Reopened The issue has been in the “Resolved” or “Closed” status and has been reopened.

The following table lists additional JIRA issue status that may be used internally by

Intrasoft:

Status Details

In Design The issue is in design at Intrasoft.

Design Complete The issue has been designed. Waiting for Approval.

Design Approved The issue design is approved.

Design Rejected The issue design has been rejected.

In Test (Intrasoft) The issue is in test at Intrasoft. Waiting for approval.

Test Approved (Intrasoft) The issue has been tested by Intrasoft and the issue is

considered resolved by Intrasoft.

Test Rejected (Intrasoft) The issue has been tested by Intrasoft and cannot be approved by Intrasoft.

ESKORT




4.1 Open status (Action Intrasoft)

The “incident report / issue” (hereinafter referred to as JIRA issue) has been created and initially assigned to the Intrasoft PM (project manager).

The JIRA issue will be reviewed by Intrasoft and updated if necessary, e.g. the Components

or Affect version field.

The JIRA issue will then either

be assigned to the Intrasoft development group or to a Intrasoft system consultant

for further analysis;

the issue can be moved to the Qualified status until work is started on the issue.

When the issue is or has been worked, it will be moved to the In Progress status.

be re-assigned to the Reporter and moved to the Pending status, if the raised issue

either

requires clarifications after analysis by the programmer or the system

consultant or

if Intrasoft considers that the issue description suggests that it is out of

scope or subject to a Change Request .

In both cases a comment will be added to the JIRA issue.

be re-assigned to the Reporter and moved to Resolved status with a Resolution of

“Answered” or “Won't Fix” if the issue is clearly out of scope and should be

subject for a Change Request.

4.2 Pending status (Action for the customer)

A JIRA issue is placed in the Pending status and re-assigned to the Reporter when Intrasoft

is requesting more information or a decision from the customer.

The Reporter should enter a comment and re-assigned the issue to the last assignee (as a

rule the last assignee is the last Intrasoft user that has entered a comment on the issue) or to

the Intrasoft Project Manager.

Normally, the issue will either be resumed in the Open status or Closed after the Pending

status.

4.3 In Progress status (Action Intrasoft)

The JIRA issue is being worked or has been worked.

A JIRA issue in the In Progress status that is assigned to the Intrasoft PM is considered fixed by the development group or the system consultant.

The “fix version” field will be updated and the issue will be moved to the In Test status and

re-assigned to the Reporter at the time where the release that includes the fix is made available to the customer.

4.4 In Test status (Action for the customer)

A JIRA issue is placed in the In Test status when the release that includes the fix is made

available to the customer.

The reporter / customer user should accept or reject the fix using the Approve Test or Reject Test workflow actions in JIRA.

In the case of a rejection, the relevant information as to why the fix is rejected should be

entered in a comment.

ESKORT




In both cases the issue can be re-assigned to the Intrasoft PM.

NOTE: The Intrasoft PM will re-assign the issue if the customer user does not!

4.5 Test Approved status (Action Intrasoft)

When a JIRA issue is in the Test Approved status, it will be moved to the Closed status

with a “Fixed” Resolution.

4.6 Test Rejected status (Action Intrasoft)

When a JIRA issue is in the Test Rejected status, it will usually be reassigned to the

Intrasoft development group or system consultant. The issue will eventually be moved to

the In Progress status when the issue is worked

4.7 Resolved status

JIRA issues in the Resolved status can either be Closed or Reopened. Issues in the Resolved (and Closed) status can have the following “Resolution”

Won’t Fix is used either

for a JIRA issue that has been entered as an Incident report or Issue type

and has been deemed out of scope.

The customer should decide if the issue should be “moved” from either the

Incident report or the Issue type to the Change Request type.

The decision should be documented by a comment in the issue and the

issue should be re-assigned to the Intrasoft PM.

or

for a JIRA issue that has been entered as a Change Request and there is an

agreement that the Change request will not be implemented

Duplicate is used when closing a JIRA issue that already is covered by or is a copy

of an already existing issue.

Answered is used either when a JIRA issue (of Issue type) has the character of a

question or request for documentation and the information has been provided.

On hold is also used when a JIRA issue has been deemed out of scope and a

decision has to be made if the change should be implemented.

4.8 Closed status

JIRA issues in the Closed status cannot be edited. They can however be reopened.

Usually a Closed issue is re-opened when the issue has not been fully solved by the fix

provided.

ESKORT




4.9 Reopened status

JIRA issues in the Reopened status have been previously either in the Resolved or Closed

status

•

jira guidelines for customers - intracom-it.dk guidelines for customers.pdf · jira the name comes...

Documents