This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Child pages
  • Guidelines for Using JIRA Draft Proposal 2

Access to add and change pages is restricted. See: https://cwiki.apache.org/confluence/display/OFBIZ/Wiki+access

Skip to end of metadata
Go to start of metadata

Important

This page is an alternative proposal regarding the guidelines for using the OFBiz JIRA instance.
Other alternative proposals are:

For now this is WIP.

Introduction

These guidelines have been created to help OFBiz Contributors to use JIRA effectively for the improvement of the various Apache OFBiz products (the code, the website, the documentation, etc). This document contains the best practices we advice our contributors to work with.

If you have a question regarding this page, or something can be improved, then please do not hesitate to post your question or remark to the OFBiz Community by sending an email to the OFBiz Development Mailing List.

What is JIRA?

Background

JIRA is the issue reporting and tracking tool the project uses.. This includes ideas for improvements, non code based work such as testing and documentation, as well as bug fixes and issues. Please see the following link to the OFBiz JIRA Summary Panel. We use our JIRA instance for all OFBiz products, like the OFBiz software, the OFBiz website and other supporting products. 

JIRA also provides a list of tasks that need to be actioned in the form of a To Do list, which can be sorted in various ways (including on priority, on current status or on the person assigned). It also can be used to generate overviews about work in progress and issue resolution.

During our OFBiz Community Days, JIRA's inbuilt agile functionalities are used to manage the backlog and create a Sprint for community members to contribute to.

If you want to find out more about how JIRA works then please see the link to the complete JIRA documentation.

JIRA Fields and Meta Data

Issue Types

When you create a OFBiz issue in our JIRA it needs to have an Issue Type. This is important because it helps to classify the issue. The OFBiz project offers the following (limited) choices:

Issue TypeDefinition and when to use this type
BugA bug is generally a problem with code or data which is not functioning correctly.
ImprovementAn improvement is something that enhances the functionality of an existing feature.
New Feature

An issue of this type is about a new functionality (set) that does not already exist.

Task

A Task is an action that needs to be carried out, that does not fall under any of the other issue types.

TestAn issue of this type is describes how a particular artefact can (or must) be tested.
WishAn issue of this type is to be used for any issue not fitting in the other types.
Sub Task

This task is a child of another JIRA issue.

This type will be set automatically when a new sub task is created via the 'More' menu of an existing issue.

Description

The issue description is the most important part of the JIRA issue as it provides the first piece of information, that will allow another contributor to investigate and resolve the issue. It must be written in such a way that it is clear enough for someone to easily understand (and potentially replicate) the problem. This means that we adivce you to provide information about:

  • What you did (e.g what application, screen, and the highlight the steps you went through etc),
  • What you were expecting to happen,
  • What actually happened.

In some case you might already have an idea about how to resolve the issue. If so then please include your suggestions as well, as this may be helpful to the next contributor picking up the issue.

Priority

All JIRA issues need a priority as it helps to determine what you (as an OFBiz contributor) want to work first. Please investigate the level 2 sections below regarding how to prioritse the various OFBiz issue types.

Labels

Issues can be classified using the label. For example an issue can be labelled as 'Beginner' indicating that it is suitable for beginners or newcomers who want to start contributing to OFBiz. Another example is to classify the issue as 'Security' indicating a security threat.

Reporter

The issue reporter is automatically assigned by JIRA based on the user profile of the person creating the Jira. Anyone (registered with JIRA) can report a new issue.

Assignee

By default when an issue is created, the assignee is blank. Any OFBiz JIRA contributor can assign himself to an issue where the Assignee is blank. 

An Assignee is the contributor that is primarily working on the issue towards a satisfactory resolution. When an issue is assigned to a contributor, the issue will be visible in the TODO list of that contributor.

For an example see the TODO list of contributor Jacques Le Roux

If an issue already has an Assignee then it means that person is still working on it. While that situation is in place, reassigning that issue to yourself without consent is inappropriate. However, it may seem that work has stalled (after a longer period of time). In such scenarios, please do not hesitate to post a message to the OFBiz Community by sending an email to the OFBiz Development Mailing List with information regarding the stalling activities and that you are willing to take over.

If you are the Assignee of an issue, and you have completed your work then once you have updated the JIRA details or comments, feel free to:

  • remove yourself as the assignee of the issue. 
  • ask another contributor to take over the issue, when you feel you can't bring it to a successful resolution.
  • ask another contributor to help you with reviewing and committing the provided patch file(s)

Component

This field determines which product component is (or, when multiple are selected, are) affected by the issue. For an overview of the product components, see https://issues.apache.org/jira/browse/OFBIZ/?selectedTab=com.atlassian.jira.jira-projects-plugin:components-panel

Flags

The choices here are:

  • Patch, or 
  • Important

Currently we don't require that this field is used.

Status

Following choices are available:

Status
Open
In Progress
Reopened
Resolved
Closed
Patch Available

Resolution

This field offers choices regarding how issues are resolved when an issue is to be closed. The appropriate resolution is determined by the issue type. More information can be found in the 'Closing Issues' section below.

Affect Version/s

This field offers all choices of OFBiz branches and releases. The affected version is determined by the issue type. More information can be found in the various issue type sections below. Setting the correct affected version(s) helps adopters to determine how the issue impacts their OFBiz implementation(s) and the experience of their users. It also helps other OFBiz contributors to decide where to spend their effort and time.

Fix Version/s

This field offers a choice regarding the OFBiz branches and releases on which the resolution of the issue is applied, or the intended resolution will be applied.

This field offers a choice of epics the issue can be associated with. Currently the OFBiz project doesn't use this. 

Sprint

This field offers a choice of sprints the issue can be associated with. Currently the OFBiz project only uses sprints for the OFBiz Community Days.

Creating an issue

In this project anyone can create an issue in our JIRA. This project project has no restrictions on who can. Anyone creating an issue is regarded as a OFBiz Contributor.

Creating an issue in our JIRA adds to the (technical) debt of the project. Therefore, creating an issue must be done with care. 
If you feel uncertain about the validity of the issue you have in mind, feel free to check with the OFBiz Community by sending an email to the OFBiz Development Mailing List. Your fellow contributors are there to help you out.
 

Working on an issue

While you're working on your issue(s) to get them to a successful resolution, do not hesitate to invite other OFBiz Contributors to provide insights or other kinds of feedback. It will help to bring the best (most acceptable) solution forward and grow the community.

We advise to bring as much information as possible to the issue in order to get it to a successful resolutions, whether that be in enhancing the description field or through comments. However, we caution to ensure that the comments provided to/on the issue are kept in sync with the intent of the issue's title and description. To much digression from that may lead to misunderstanding and/or scope creep. If you feel that comments provides warrants an new issue, suggest the poster of that comment to create one.

If you feel that the issue entails more effort and time than initially expected, consider splitting the issue up in sub-tasks or relating issues. It may help triggering other contributors to pitch in more.

Getting your patch file(s) reviewed

If you have provided your patch file(s) to the issue and you feel confident that the work is done, invite fellow OFBiz contributors to act as reviewers by sending a message to the OFBiz Development Mailing List.

The issue you're working on need not to be reassigned for that activity. 

Should the review uncover any flaws, work or collaborate to get these resolved. Should the review uncover any new issues, we advise to create new OFBiz issues accordingly.

Getting your change(s) committed

If, after review, no obstructions - to have the patch file(s) committed to the appropriate development branches - appear to exist, we advise you to send a message to OFBiz Development Mailing List to invite a contributor with commit privileges to persist the changes in the patch file(s) in the suggested branches. 

In order to get your contribution(s) in the form of (one or more) patch files committed, the issue need not be reassigned to the contributor with the commit privilege. This contributor is there to assist you to get the issue successfully resolved.

Closing an issue

Successful resolution

When the changes provided to issues of the type BugImprovement and New Feature  have been committed to the appropriate branch(s) for the given product(s)/component(s), it is time to close the issue. As we have different kinds of OFBiz issues (see section 3.1), so does the resolution type differ accordingly. Please set the resolution type of the issue in accordance with following schema:

Issue typeResolution TypeExplanation
BugFixed 
ImprovementImplemented 
New FeatureImplemented 
Sub-Task To be set in accordance to the type of the parent (placeholder) issue. E.g. if the parent issue is of the type 'Bug', then the sub-task must be resolved as such.
TaskCompleted 
WishT.b.d 

 

Unsuccessful resolution

Should you, while working on the issue, realise that the issue doesn't exist anymore or was created under an unintentional misbelief, we advise you close the issue at the earliest convenience in accordance with following schema:

Issue typeResolution type(s)Explanation
Bug  
Improvement  
New Feature  
Sub-Task To be set in accordance to the type of the parent (placeholder) issue. E.g. if the parent issue is of the type 'Bug', then the sub-task must be resolved as such.
Task  
WishT.b.d. 

Reopening a closed issue

Issues that have been closed with a successful resolution should not be reopened. If such

T.b.d.

Bug Issue

Background

A bug is generally a problem with code or data which is not functioning correctly.

Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Improvement issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

Please consider the following schema for OFBiz Improvements when setting the priority you create (as the reporter) or when you are the assignee:

Priority
Current JIRA Definition
Re: Bug
Proposed Revised Definition and when to to use this priority
BlockerBlocks development and/or testing work, production could not run

A blocking issue an issue with a released OFBiz version (or development branch) that does not run, does not comply with the legal requirements of the Apache Software Foundation, is a security vulnerability to the OFBiz adopter or exposes the project to an unacceptable risk.

CriticalCrashes, loss of data, severe memory leakA critical issue is an issue with a released OFBiz version (or development branch) that causes the system to crash, become unstable, lose data and has no workaround.
MajorMajor loss of functionA major issue is an issue with a released OFBiz version (or development branch) that has a significant impact due to loss of function and has no or limited workarounds.
MinorMinor loss of function or problem where easy workaround is presentA minor issue is an issue with a released OFBiz version (or development branch) that has isolated minor impact.
As an example: typo's in OFBiz Labels and missing OFBiz Labels can be regarded as a bug of minor priority. 
TrivialCosmetic problem like misspelt words or misaligned textDon't use this for bug issues, as bugs are never trivial.

Affected Version/s

For bug issues the 'Affected Version/s' field should be set to one (or more) releases and/or branches in accordance with the following list:

  • any available release
  • any available release branch
  • Trunk

Setting the correct affected version(s) helps other adopters to determine how the issue impacts their OFBiz implementation or the experience of their users. It also helps other OFBiz contributors to decice where to spend their effort and time.

Fix version/s

For bugs the 'Fix Version/s' field should be set to one (or more) releases and/or branches.

Be aware that the projects reserves her rights to apply the provided patch file(s) to any other (and available or future) release or branch.   

Improvement Issue

Background

An improvement is something that enhances the functionality of an existing feature in one or more products/components.

Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Improvement issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

Please consider the following schema for OFBiz Improvements when setting the priority you create (as the reporter) or when you are the assignee:

Priority
Description / Explanation
Blocker

Don't use this for improvement issues, as improvements can never be blocking.

CriticalClassifying the issue with this level indicates that the issue impacts multiple products/components. Placeholder issues (issues encompassing multiple sub-tasks and/or other linked issues) can have this setting.
MajorClassifying the issue with this level indicates that the issue impacts multiple elements within one product/component.
MinorClassifying the issue with this level indicates that the issue impacts a single element within one product/component.
TrivialClassifying the issue with this level indicates that the issue impacts a cosmetic aspect in the code within one product/component, e.g. typo's in code comments.

Review

Patch files submitted to an issue of this type and having the priority (impact) setting Critical and Major must always be reviewed by fellow contributors before being committed to a branch. Multiple aspects must be evaluated and assessed before the commit happens, like:

  • adherence to coding conventions,
  • performance impact,
  • security impact,
  • t.b.d.

Affected Version/s

For improvement issues the affected version should be set to one (or more) releases and/or branches in accordance with the following list:

  • any available release
  • any available release branch
  • Trunk

Setting the correct affected version(s) helps adopters to determine how the issue impacts their OFBiz implementation(s) and the experience of their users. It also helps other OFBiz contributors to decide where to spend their effort and time.

Fix Version/s

Patches of OFBiz Improvement issues will be applied to a specific Fix version, called 'Upcoming Branch'. This is to easily determine which OFBiz Improvement issues go into the next (future) development branch.

Be aware that the projects reserves her rights to apply the provided patch file(s) to any other (and available or future) release or branch.  

New Feature Issue

Background

An issue of this type is about a new functionality (set) that does not already exist in any of the OFBiz products/components.

Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Feature issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

Review

Patch files submitted to an issue of this type must always be reviewed by fellow contributors before being committed to a branch. Multiple aspects must be evaluated and assessed before the commit happens, like:

  • adherence to coding conventions,
  • performance impact,
  • security impact,
  • t.b.d.

Affected Version/s

For New Feature issues the affected version need not to be set when creating the issue. However, when providing patch files this field can be used to indicate against which version the files can be applied to test against (in accordance with the schema provided below).

  • any available release
  • any available release branch
  • Trunk

Setting the correct affected version(s) helps adopters to determine how the issue impacts their OFBiz implementation(s) and the experience of their users. It also helps other OFBiz contributors to decide where to spend their effort and time.

Fix Version/s

Patches of OFBiz New Feature issues will only be applied to a specific Fix version, called 'Upcoming Branch'. This is to easily determine which OFBiz Improvement issues go into the next (future) development branch.

Task Issue

Background

A task is an action that needs to be carried out, that does not fall under any of the other issue types. This kind of issues can be used to keep tabs on issues registered in the issue tracking solutions of other ASF Offices or Projects, or other (outside) organisations and setups.

 Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Task issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

The priority of this kind of OFBiz issues should be set in accordance to the consensus within the OFBiz Community.

Affected Version/s

For now, this field should not be used.

Fix Version/s

For now, this field should not be used.


Wish Issue

Background

An issue of this type is to be used for any issue not fitting in the other types.

Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Wish issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

Please consider to explain why you (as a reporter or assignee) prioritise the issue as you did. It helps other OFBiz Contributors to understand.

Affected Version/s

For now, this field should not be used.

Fix Version/s

For now, this field should not be used.

Sub-Task Issue

Background

This task is a child of another JIRA issue.

This type will be set automatically when a new sub task is created via the 'More' menu of an existing issue.

We advise to keep sub-task issues in line with the parent (placeholder) issue. If the parent issue is of the type Improvement then the sub-task issues are to be regarded of the same type.

Priority

As there is no obligation to contribute it is difficult - at project level - to prioritise an OFBiz Improvement issue. However, every contributor can set the priority of the issue, he is assigned to, in accordance with his schema, desire and/or conviction. Any priority set does not imply an enforceable action.

Please consider to set the priority (of the sub-task) not higher that the priority of the parent (place-holder) issue. Also consider to explain why you (as a reporter or assignee) prioritise the issue as you did. It helps other OFBiz Contributors to understand.

Affected Version/s

For improvement issues the affected version should be set to one (or more) releases and/or branches in accordance with the following list:

  • any available release
  • any available release branch
  • Trunk

Setting the correct affected version(s) helps adopters to determine how the issue impacts their OFBiz implementation(s) and the experience of their users. It also helps other OFBiz contributors to decide where to spend their effort and time.

Fix Version/s

Patches of OFBiz Improvement issues will be applied to a specific Fix version, called 'Upcoming Branch'. This is to easily determine which OFBiz Improvement issues go into the next (future) development branch.

Be aware that the projects reserves her rights to apply the provided patch file(s) to any other (and available or future) release or branch.  

Missing OFBiz products/components in JIRA

If you should experience that you can't assign your issue to a particular OFBiz product or component, please post your question or remark to the OFBiz Community by sending an email to the OFBiz Development Mailing List

6 Comments

  1. Pierre, why did you copy Sharan's work she started here: Guidelines for Using JIRA Draft Proposal 1 ?

    1. Michael,

      Your question is based on a wrong assertion. Please check your facts and consult with your peers  and/or other counsel.

      1. I might be mistaken but the initial version looked very similar to Guidelines for Using JIRA Draft Proposal 1 to me.

        Anyway, having to different versions of JIRA guidelines on the same Wiki level in root may confuse our users. To avoid this, I have created an overall page for the guidelines with a short notification of the work in progress and put the two versions under it.

        I also renamed both articles to look the same and clearly state that these are proposals.

        I hope that this helps to avoid confusion.

  2. Should we not agree on something and link it from OFBiz Contributors Best Practices ?

     

    1. Both proposals are in a draft state, I don't think that we should link to any of them.

      The drafts have to be finished to decide which one to use or merge them.

  3. OK, so I'll put my hands in that soon (smile)