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 | |
|---|---|
|
Non technical / Quickstart
Just add your input as a story on JIRA 
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:
Bug
- A problem which impairs or prevents the functions of the product.
Task
- A (small) task that needs to be done.
Improvement
- An improvement or enhancement to an existing feature or task.
New Feature
- A suggested new feature of the product, which has yet to be accepted to be included in the final product.
Story
- A simple feature, or action. (Accepted to be included in the final product)
- A concrete single feature or action, often part of a bigger epic
- For simplicity: refrain from using this, use epics insteadAn 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.
Epic- A more complicated feature or action which needs to be broken down. (Accepted to be included in the final product)A larger concept of a set of features or actions
Discussion
- 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 taskstory.
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'. When in doubt whether to assign story or epic, choose epicHowever 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:
- 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
- Formulate the summary in a short, clear and imperative way
...
- Improvement:
- 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
- Formulate the current behaviour
- Bug reports:
- 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
- Formulate the summary in a short and clear way. Leave out the subject of the sentence.
- Discussion:
- 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:
...
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.
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!