Versions Compared

Old Version 6

changes.mady.by.user Fabrizio Bellicano

Saved on

compared with

New Version Current

changes.mady.by.user Rik Smale

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Differences between task, bug, improvement, new feature, and the like:

...

  • NEW FEATURE: When you propose a new feature that is necessary to complete a user story
  • TASK: When you are not sure about the category, just use this

...

(star)Note: If you see a new feature belonging to a user story, then link it there. Otherwise, just file a new user story. The project manager will break it down

Example of user story:

A user story is always written using natural language, in this form

"As a <type of user>, I would like to <desired goal> such that <desired outcome>"

E.g. "As a board member of my antenna, I would like to see where my members attend events such that I can have prizes for the ones who travelled the most"

At that point, the project manager will add the corresponding tasks to achieve this goal (in the form of "new feature").

...

Since we are working with lots of different people it is important we record issues in a clear consistent and concrete way, therefore these guidelines should always be followed. (Not just in OMS-General, but in every module)
This page is based on the official JIRA constants page, however, stick to the convention laid out here when working on the OMS project. 

While we encourage you to try and follow these guidelines, do not let these keep you from contributing!


Table of contents

Table of Contents

Non technical / Quickstart

Just add your input as a story on JIRA (smile)
If possible read this document and try to follow it.

Issues

Issue types

JIRA is used as an issue tracker, here the term 'issue' is a very vague term, it does not necessarily mean that something is wrong with the software (a bug) but can also be a new feature.
An issue can be one of the following:

  • Image AddedBug
    • A problem which impairs or prevents the functions of the product.
  • Image AddedTask
    • A (small) task that needs to be done.
  • Image AddedImprovement
    • An improvement or enhancement to an existing feature or task.
  • Image AddedNew Feature
    • A suggested new feature of the product, which has yet to be accepted to be included in the final product.
  • Image AddedStory
    • An issue of which the issue type is not further specified.
    • New users: Use stories and just give your input, we will further categorize it for you.
  • Image AddedEpic
    • A more complicated feature or action which needs to be broken down.
  • Image AddedDiscussion
    • A subject related to the project that needs discussion or feedback.

When filing a new issue, think about what kind of issue it is and if unsure label it as a story.

Story vs Epic

We have had an internal discussion about when to use a story and when to use an epic. The conclusion was that there is no real definition to either or on the difference between them. In the end, we decided to mostly go with epics because these have some extra functionality such as having sub-stories and some filter options in the dashboard. The definition we will use for an epic will be 'A larger concept of a set of features or actions', the definition of a story will be 'A concrete single feature or action, often part of a bigger epic'. However we have decided that it would be easier to use stories as a standard go-to issue type for less technical contributors.

Issue syntax

When creating a new issue please take the following conventions in account. These conventions are split between bugs and non-bugs:

  • Suggestions: Image AddedImage AddedImage AddedImage Added
    • Formulate the summary in a short, clear and imperative way
      • Add a couch surfing mechanism
      • Give newly registered users an O365 account
    • Formulate the description in an explaining, extensive, and natural way
      • As an AEGEE-member, I would like to use the OMS to easily find a place to couch surf.
      • As a newly registered user, I would like to receive an office-365 account for personal use.

    • Add examples and other information at the end of the description

    • Make it clear, avoid confusion
  • Improvement:Image Added
    • Formulate the current behaviour
      • When I press the event page I am to able to filter on the dates of the event.
    • Formulate the intended behaviour
      • When I press the event page I am also able to filter on end date of the application period.
    • Add examples and other information at the end of the description
    • Make it clear, avoid confusion
  • Bug reports: Image Added
    • Formulate the summary in a short and clear way. Leave out the subject of the sentence.
      • Cannot save a news story
      • Error when loading a page while impersonating
    • Formulate the description in a detailed explanation of how to reproduce the bug.

      • Steps to reproduce:

        • Find a user to impersonate
        • Press impersonate
        • The page reloads and the following notification shows twice:
          Permission error!
          Not enough permissions!
    • Use screenshots or other attachments to make things more clear!
    • Add examples and other information at the end of the description
    • Make it clear, avoid confusion
  • Discussion: Image Added
    • Formulate the summary in a clear and concrete question
    • Add extra information and context to the description
    • Keep the summary and description objective, voice your opinion in the comments.

Issue priorities

For the priorities we will use the standard definitions given by JIRA:

  • Image Added Highest
    • This problem will block progress.
  • Image Added High
    • Serious problem that could block progress.
  • Image Added Medium
    • Has the potential to affect progress.
  • Image AddedLow
    • Minor problem or easily worked around.
  • Image AddedLowest
    • Trivial problem with little or no impact on progress.

When in doubt assign the 'Medium' priority

Workflow

JIRA has a build in workflow system, where an issue can move to certain states using predefined transitions. This system helps us know/remember/communicate in what kind of a state a certain issue is. While working on an issue you should follow this workflow and update it appropriately. In the end the states of the issues (especially to do states vs done states) help us determine the state of the overall project. Below is the overview we use for any non-bugs issues. You can always press view workflow in JIRA.

Image Added

Planning

JIRA has a pretty awesome planning tool called portfolio. In here we define multiple cross-project releases and specify which issues should be in which release. Important for you to know is that you can see the issues that should be done first by having a look at the releases of the project you are working on. While Derk Snijders is mainly responsible for setting the releases, you can always approach him with feedback/suggestions on it!

JIRA integrations

  • We integrated JIRA with Slack in order to be able to keep track on changes in issues from the safety and comfort of Slack.
  • JIRA is also integrated with Git, when you use a JIRA issue code (ie. 'CORE-33') in your branch/commit/pull-request, it automatically links to it on the issue page!