A guide for writing tickets in JIRA

Jira can help you keep track of all your work in one place. With organized boards, lists and other views, it is easier to decide what you should be working on next. Jira is also helpful when you need to collaborate and share your workload efficiently.

As a rule of thumb, whenever you run into a task that you are not able to complete right away, you should probably create a Jira issue of it. This can prevent you from forgetting things, even though it may sometimes feel a bit silly.

You can create a new JIRA ticket or issue by clicking on the Create button on top of the window after logging in. (You may also create an issue from this link: https://jira.csc.fi/secure/CreateIssue!default.jspa, but this is generally not recommended).

Parts of a Jira issue

There are more fields than the ones shown below, but these are the ones that are recommended for our purposes. In case you don’t see all of the fields, you may select them by clicking on Configure Fields in the top right corner of the dialog box.

Project: Kielipankki (KP) is one of the ”Projects” in Jira (although, unlike normal projects, it does not have an end date).

Issue Type: In our Jira setup (our ”Kanban implementation”), several ticket types are included. The purpose of the types is to give an idea of the nature of the issue, e.g., whether it is

  • a Bug that needs fixing,
  • an Epic, a large chunk of work that will probably take months or even longer to complete and will contain a number of various kinds of tasks,
  • a Story that will probably take several days of work and may potentially include subtasks, or
  • a short and simple Task.
    (See JIRA Practices for details.)

Summary: A concise gist of the work to be completed. The purpose of the summary is to make it possible for the reader to quickly see what the goal of the issue is, i.e., ”who needs what and why”.

  • If there are several stages in the work, you should create subtasks.
  • In case there are several goals that are related to one another, create several issues and add links between them (select More:Link in the Issue view).
  • In some Board views, only the initial portion of the Summary (or the Epic Name) will be displayed, which you should consider if you end up writing a lengthy Summary line. A further specification of the goal should be provided in the Description, see below.
  • Note that the summary is not ”a title of the subject area”. In case the goal is unclear, the issue may never get done, since you cannot easily tell whether it has been completed. (If you were assigned an unclear issue, you should assign it back to the Reporter and ask for a clear specification.)

Priority should be set if known. See JIRA Practices for details.

Reporter: usually you.

Labels are tags or keywords that you may use in order to be able to efficiently search and filter your issues. You might include the work package a task or story belongs to, e.g., ”UPGRADE-WP1”, the type of work, e.g., ”documentation”, or the type of corpus, e.g., ”text” or ”speech”. Please invent labels that you are likely to use again in other issues.

Assignee is the person responsible for completing the work. Can be assigned if known, otherwise the  default person of the component will be assigned. In case different people will be completing parts of the work, you should additionally create subtasks or linked tasks for them, so as to keep the present issue visible to the current Assignee.

Attachments are files attached to the issue. Please note that depending on the security settings of the issue, the attachments may be publicly visible.

Security Level: Access permissions to see the issue and its content. None or All allows general access for logged in users, Administrators only to admins (CSC, National Co-ordinator). Devel allows access to the members of the Kielipankki project team (at University of Helsinki / CSC), and Suppl (Suppliers) gives additional access to affiliated developers, like the ones for Signbank or Sanat. The default is ”Devel”. Comments are only visible according to the Security Level of the issue, they can be further restricted.

Components: The main parts or sections of the project, i.e., in our case, Kielipankki. Components have owners, e.g., Krister owns Dissemination and Coordination, Tero owns Portal, Mietta owns Teaching. Ideally, you should have an idea about the category. But if you don’t, you can leave it blank. You may also include several Components when you see fit. Note that typically, the owner of the Component will get automatic emails about all or most changes in the issues within that Component.

Description: The free text field specifying the goals or requirements of the issue in more detail. The Description should be concise enough so as to know when the Assignee (or a person reviewing the issue) may consider the issue as Done. When writing the Description, you should consider situations where the original Reporter and/or Assignee are no longer available and someone else needs to take up the issue. Can the reader understand what needs to be done or where the necessary information is? Respect user’s privacy, do not unnecessarily disclose personal information in issues and never disclose it in issues open to all Jira users (Security Level: All or None).

Due date: You should set a due date whenever possible, since it helps the Assignee to keep track of issues. Combined with the Priority setting, the due date will make it easier for you and the rest of the team to determine what should be done next. In search filters, on Kanban boards and elsewhere in Jira, issues can be selected or sorted according to their due dates.

Tip: You can make JIRA send you reminders of issues, for instance of those with due dates that are closing up. First, select or find the desired search filter (Issues > Filters) or create and save your own filter (select Issues: Search…) and then subscribe to it (select Issues > Filters > more…). Further instructions on this:

Epic Link: In case you are creating a Task or a Story that is part of an Epic, for instance if the new issue is included in the publication process of a specific corpus, you can add a link to that Epic here. Just begin typing the name of the Epic and you will see a list of the existing options. An issue can have only one Epic Link at a time. (If the corresponding Epic does not yet exist, you may edit the issue and add the link later.)

Search the Language Bank Portal:
Tommi Kurki
Researcher of the Month: Tommi Kurki

 

Contact

The Language Bank's technical support:
kielipankki (at) csc.fi
tel. +358 9 4572001

Requests related to language resources:
fin-clarin (at) helsinki.fi
tel. +358 29 4140599 / +358 29 4129317