THIS IS A TEST INSTANCE. ALL YOUR CHANGES WILL BE LOST!!!!
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 builtin agile functions 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 Type | Definition and when to use this type |
|---|---|
| Bug | A bug is generally a problem with code or data which is not functioning correctly. |
| Improvement | An improvement is something that enhances the functionality of an existing feature, not being a bug. |
| 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. |
| Test | An issue of this type is describes how a particular artefact can (or must) be tested. |
| Wish | An 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) or another community member want to work on 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 current (actively maintained) and past OFBiz branches and releases. 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, as well as the adopter's developers to determine whether the patches attached to the ticket may apply to the implemented version or might need some adjustment.
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.
Epic Link
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 (files) reviewed
If you have provided your patch (files) 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 (files) committed to the appropriate branch(es) - 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 (files) into the suggested branch(es).
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 community member 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 Bug, Improvement 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 type | Resolution Type | Explanation |
|---|---|---|
| Bug | Fixed | |
| Improvement | Implemented | |
| New Feature | Implemented | |
| 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 | Completed | |
| Wish | Yet to be determined by the project. |
Unsuccessful resolution
Should you, while working on the issue, realise that the issue doesn't exist anymore or was created under an (un)intentional misbelief, we advise you close the issue at the earliest convenience in accordance with following schema:
| Issue type | Resolution type(s) | Explanation |
|---|---|---|
| Bug |
|
|
| Improvement | Yet to be determined by the project. | |
| New Feature | Yet to be determined by the project. | |
| 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 | Yet to be determined by the project. | |
| Wish | Yet to be determined by the project. |
Reopening a closed issue
Issues that have been closed with a successful resolution should not be reopened.
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 |
|---|---|---|
| Blocker | Blocks development and/or testing work, production could not run | A blocking issue an issue with a released OFBiz version (or 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. |
| Critical | Crashes, loss of data, severe memory leak | A critical issue is an issue with a released OFBiz version (or branch) that causes the system to crash, become unstable, lose data and has no workaround. A critical issue may also be one that is detrimental to the reputation of the product and/or the project. |
| Major | Major loss of function | A major issue is an issue with a released OFBiz version (or branch) that has a significant impact due to loss of function and has no or limited workarounds. |
| Minor | Minor loss of function or problem where easy workaround is present | A minor issue is an issue with a released OFBiz version (or 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. |
| Trivial | Cosmetic problem like misspelt words or misaligned text | Don'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. This is typically set by a privileged contributor after he/she has merged the patch into a branch in the repository.
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. |
| Critical | Classifying the issue with this level indicates that:
|
| Major | Classifying the issue with this level indicates that the issue impacts multiple elements within one product/component. |
| Minor | Classifying the issue with this level indicates that the issue impacts a single element within one product/component. |
| Trivial | Classifying 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
Patches submitted to an issue of this type and having the priority (impact) setting Critical and Major must always be reviewed by multiple 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'. The 'Fix Version(s) attribute is typically set by a privileged contributor after he/she has merged the patch into a branch in the repository. 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.
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 'New Feature' issues, as these can never be blocking. |
| Critical | Classifying the issue with this level indicates that:
|
| Major | Classifying the issue with this level indicates that the issue impacts multiple elements within one product/component. |
| Minor | Classifying the issue with this level indicates that the issue impacts a single element within one product/component. |
| Trivial | Classifying 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
Patches submitted to an issue of this type and having the priority (impact) setting Critical and Major must always be reviewed by multiple 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 patches 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 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'. The 'Fix Version is typically set by a privileged contributor after he/she has merged the patch into a branch in the repository. 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 (dev@ofbiz.a.o).