Page History

For now this is WIP.

Introduction

These guidelines have been created to help our community OFBiz Contributors to use JIRA effectively for Apache OFBiz development. These are the best practices that we want all contributors to follow. 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 is unclearcan be improved, then please don't hesitate to ask for help on the OFBiz development mailing list.

PLEASE NOTE: This page is a WIP

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 and can be one of the following type:. The OFBiz project offers the following (limited) choices:

Summary

This is a brief title for the issue and summarises what the issue is about. It must give us the key information. Try to focus on the actual issue that you are facing as this will help us quickly identify and classify it.

Other examples of good JIRA summaries

• Create a separate SVN repository for OFBiz official plugins
• Add the auto-entity CRUD services for Runtimedata
• View Sales Order throws exception in getReturnableQuantity
• Not able to select virtual products in WebPos

Description

The issue description is the most important part of the JIRA issue. If you are reporting a bug or problem then it provides information that will allow someone else to investigate and resolve it. It must be written in such a way that it is clear enough for someone to easily replicate the problem. This means that you need to include 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 cases you might already have an idea about what is causing the issue. If so then please include your suggestions as this may be helpful to the person picking up the issue.

e.g (ADD AN EXAMPLE)

If the issue is about some project work that is planned (e.g refactoring, documentation etc) or agreed after a community discussion then please use the description is used to highlight the steps needed to get the work done. Add a reference back to the community discussion if relevant.

Example

This issue is related to the discussion found in this thread in which the community approved restructuring our repositories. To achieve this task the following needs to be done (in this order)

1. Update the gradle scripts to assume that no plugins exist in the plugins directory by default and no component-load.xml exists. It should follow the same logic in loading the components as found in the ComponentContainer class. Also the activation and deactivation of plugins happens in ofbiz-component.xml, not in component-load.xml
2. Add a new task to gradle called pullPluginSource that retrieves a plugin from subversion and defaults to the official plugins repository of Apache OFBiz. This task mostly server "Trunk" because it always needs the latest source code of the plugins.
3. delete plugins/component-load.xml
4. move all plugins to a new repository called http://svn.apache.org/repos/asf/ofbiz/ofbiz-plugins
5. move the core framework to a new repository called http://svn.apache.org/repos/asf/ofbiz/ofbiz-framework
6. fix buildbot to point to the new framework location
7. update documentation where applicable including README.md

Priority

All JIRA issues need a priority as it determines what needs to be worked on. This is important because it helps to ensure that the community is focussed and working on the right tasks.

• OFBiz has several versions of the code base available as released and unreleased branches, as well as the trunk and JIRA covers all of them.
• Blocking and Critical issues are generally reserved for problems with production systems (i.e systems that customers use). 
• The OFBiz 'production systems' are our officially released versions that have been signed and approved for release and issues here are the highest priority.

...

A blocking issue an issue with a released OFBiz version that does not run, causes the system to crash, is security vulnerability to users or exposes the project and Apache Software Foundation to significant risk

...

A major issue is an issue with a released OFBiz version that has a significant impact due to loss of function and has no or limited workarounds

...

Labels

Labels are a way to classify issues. 

• For example an issue can be labelled as 'Beginner' indicating that it is suitable for beginners or newcomers who want to begin contributing to OFBiz, or 'Documentation' for document related tasks.

An issue can have more than one label and JIRA allows you to create new labels automatically if the one you need does not already exist.  Please be careful that you are not using the label as an indicator for the OFBiz 'Component'  as we already have a component field in JIRA to define the OFBiz component or application area.

...

NOTE: The following list is a suggested list of labels that could be used to locate specific areas within the OFBiz components. This list is significantly reduced from the existing labels for OFBiz issues.

Proposal

Clean up all existing open issues by removing any non standard labels and assign issue to the appropriate component

...

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:

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

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:

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:

Reopening a closed issue

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:

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:

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:

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).

Reporter

The issue 'Reporter' is the person that creates the issue. This is automatically assigned by JIRA based on the user profile of the person creating the Jira.

Assignee

The 'Assignee' is the person that is currently working on the JIRA issue. By default when an issue is created, the assignee is blank.

• If the assignee field is blank then any OFBiz JIRA Contributor can assign themselves to it to work on it.
• If the assignee field is not blank (i.e it already has someone's name in it, then it means that that person is still working on it).
  

If you are an Assignee for an issue and you have completed your work then once you have updated the JIRA details or comments, please unassign yourself from the issue. (i.e remove your name from the assignee field). This is important if the work is a patch that needs to be committed. Our Committers will be able to see the unassigned tasks that are available to be picked up, review them and if necessary commit them

If you know have arranged with someone to take over your work on an issue, then when removing your name from the assignee field, you can add the person you have arranged to take it over.

Component

The 'Component' field is very important. It is used to identify which OFBiz component or application area is affected by the issue.This makes searching for issues related to a specific component very easy. JIRA also provides a small dashboard of the recently updated issues.

Each component can have a different lead. The component lead is a person that is assigned to be responsible for managing or co-ordinating the issues for a specific component.  (NOTE: This could be a very good way to share the workload by enabling committers to take responsibility for a specific area. For example a component lead could review the issues for their area and plan for the implementation of patches and working on bug fixes.)

An issue could also be across more than one applications or it could affect all applications.

NOTE: Be careful that that details in the Labels field is not being duplicated.

DO AN EXTRACT OF THE LIST OF COMPONENTS WE HAVE

DO WE STILL NEED TO HAVE THE SAME LIST OF COMPONENTS / WE HAVE RENAME OF PLUGINs

The following is a list of the existing JIRA components for OFBiz with their current Component Leads.

...

ALL APPLICATIONS

...

ALL COMPONENTS

...

Attic

...

base

...

BuildBot

...

commonext

...

Confluence

...

content

...

datamodel

...

Demo

...

framework

...

framework/webtools

...

Gradle

...

humanres

...

manufacturing

...

marketing

...

order

...

party

...

POS

...

product

...

securityext

...

site

...

specialpurpose/appserver

...

specialpurpose/assetmaint

...

specialpurpose/bi

...

specialpurpose/birt

...

specialpurpose/cmssite

...

specialpurpose/ebay

...

specialpurpose/ebaystore

...

specialpurpose/ecommerce

...

specialpurpose/example

...

specialpurpose/exampleext

...

specialpurpose/googlebase

...

specialpurpose/googleCheckout

...

specialpurpose/hhfacility

...

specialpurpose/ldap

...

specialpurpose/lucene

...

specialpurpose/myportal

...

specialpurpose/oagis

...

specialpurpose/passport

...

specialpurpose/pos

...

specialpurpose/projectmgr

...

specialpurpose/scrum

...

specialpurpose/solr

...

specialpurpose/webpos

...

start

...

themes

...

Flags

There are two flags available on a JIRA issue. One flags that the issue is a Patch and the other that the issue is Important.

JIRA already provides a 'Provide Patch' button for an issue so the Patch flag here is a duplication of functionality. Some of the issues include it as well as the patch, and some don't. (We may need to look at revising how we use this flag)

JIRA also already provides a 'Priority' field for an issue so the Important flag seems like a duplication of functionality.

DO AN EXTRACT OF THE LIST OF ISSUES USING FLAGS

Status

The status field tracks the current status of an issue from creation to resolution or closure.

Affect Versions

Fix Versions

DO WE MAKE THIS INTO A FAQ STYLE PAGE???

Creating JIRA Issues

Creating issues in JIRA adds to the project workload so it is important that they are created when needed and with the right level of information that will help someone to pick it up and resolve it as soon as possible.

When Not to Create a Jira Issue

• If you want general OFBiz help or advice
• If you want to know which version to use
• If you want to talk about anything related to your specific OFBiz implementation
• If you want to know how other users manage a process or function
• If the issue has already been reported and exists in the current list of issues
  

Instead please post your question or comments on our user or development mailing lists and someone from our community will respond to you.

Discussion Point

• If you have an idea for a new feature or improvement
  
  •  If you don't have a patch, and you want to suggest an enhancement or new feature, then discuss this in the dev mailing list instead of creating a Jira issue; at the end of the discussion, the community will consider if a summary of the thread should be saved in a new Jira issue, to facilitate future development
  • If you don't have a patch, but you are planning to work on it, and you want to share your design details with the community, you should discuss this in the mailing list instead of creating a Jira issue

Many people use OFBiz so there is a chance that issue you have encountered may have already been reported. You can search JIRA using the keyword search to see if anything with a similar topic has been created. There is a 'Search' box in the top right of the main JIRA screen and this searches across all ASF projects. All OFBiz issues have the format 'OFBIZ-9999'

Another way to search issues is by clicking the 'Issues' link on the left hand column and then 'All Issues'. An advanced search query filter box is displayed that allows the user to enter their search criteria. The query box is user friendly and offers interactive lookup on the query commands as you type. See below for an example of a query to find all issues that have the word 'accounts' in their description

project = OFBIZ and description ~accounts

When  to Create a JIRA Issue

Reminder: Before creating a JIRA issue, please check that it has not already been reported.

• If you have discovered a bug that has not yet been reported
• If you have identified a bug then also fixed it and want to contribute the fix back to the project, then you can create an issue and attach your patch to it. (Note if the issue has already been created then attach your patch to the existing issue and do not create a jira) 
• If after a community mailing list discussion the recommendation is the create a JIra (e.g. new features, improvements etc)

Discussion Point :

 if, on the other hand, you don't have time to do this, (i.e. to discuss the design solution with the community) you have already decided that you want to implement your patch following your design notes, and you just want to let the community know about the upcoming patch, you can create a Jira issue (to which you will attach your patch when it is ready

• Doing this means that patches for improvements and new features can get uploaded to JIRA and the community has not discussed or agreed they want them or are necessary
• Are we trying to use JIRA like a patch code repository too? If so then is JIRA the best place to do it? How do we make the distinction between patches that are contributed and are accepted to the repository and those that are not acceptable due to whatever reasons (coding, design etc)

How to Create a JIRA Issue

1. You need a JIRA account so if you do not have one then create an account here
2. Login to your JIRA account
3. Click 'Create' at the top of the screen to create a new issue and a screen form will be displayed for you to fill in
4. Project: OFBiz should the default project for the issue. If it is not then please select it from the dropdown selection box
5. Issue Type: Bug is the default so please change this if your issue belongs to a different issue type
6. Priority: Major is the default priority. Please review the guidelines around assigning a priority and change it if necessary
7. Component: Select the OFBiz component that is affected by the issue you are creating. If all components are affected select ALL_COMPONENTS 
8. Affect version: Select the OFBiz version that is affected by the issue you are creating. I
9. Assignee: If you are going to work on this issue yourself the enter your name
10. Reporter:  The name of the person creating the issue should be automatically default as the reporter
11. Environment: Specify at least your operating system and the database you are using for OFBiz as this information could be very useful to help people working on the issue. If you are running the trunk then please specify the SVN revision number
12. Description:

1. If you need to attach files such as patches you must do it as a second step after the issue creation. It is also possible to easily attach screenshots to the issue see here
   • When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed togheter far from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
   • Also please use preferably .patch as extension for patches. When updating an attached file keep the same name : Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its usefull to compare older patches versions)
   • If you provide a patch, be sure to use the button "Provide Patch" (the status will then be "Patch Available"). This allows us (commiters) to know that this issue is ready for review.
2. Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more)

How to Update a JIRA Issue

...

1. (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
2. (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it

...

• Generally it is very important to select in the "Affect version" field the ofbiz version you are running. If you are running the trunk then the SVN revision should also be specifyed in the Environment field
• Use the Environment field to specify at least your operating system and the database ofbiz is using since these information could be very useful to help people to work on the issue
• Select the concerned component(s). If all components are affected select ALL_COMPONENTS (uncommon case)

...

• When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed togheter far from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
• Also please use preferably .patch as extension for patches. When updating an attached file keep the same name : Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its usefull to compare older patches versions)
• If you provide a patch, be sure to use the button "Provide Patch" (the status will then be "Patch Available"). This allows us (commiters) to know that this issue is ready for review.

How to create a Jira issue
 

1. Create an account here, if you do not have one
2. Login
   1. (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
   2. (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it
3. If a issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
4. Select the OFBiz project and the issue type.
5. Fill in all fields, give as many detail you think necessary
   • Generally it is very important to select in the "Affect version" field the ofbiz version you are running. If you are running the trunk then the SVN revision should also be specifyed in the Environment field
   • Use the Environment field to specify at least your operating system and the database ofbiz is using since these information could be very useful to help people to work on the issue
   • Select the concerned component(s). If all components are affected select ALL_COMPONENTS (uncommon case)
6. If you need to attach files such as patches you must do it as a second step after the issue creation. It is also possible to easily attach screenshots to the issue see here
   • When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed togheter far from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
   • Also please use preferably .patch as extension for patches. When updating an attached file keep the same name : Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its usefull to compare older patches versions)
   • If you provide a patch, be sure to use the button "Provide Patch" (the status will then be "Patch Available"). This allows us (commiters) to know that this issue is ready for review.
7. Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more)

If you don't have a patch, and you have discovered a bug, create a Jira issue (if there is not one already) providing as much details as possible (including the rev. number and the environment you are using, and the step to recreate the bug). if you have no ideas how to describe the bug use this template

1. What you did (including detailed steps to reproduce)
2. What you expected to happen
3. What actually happened (including exact quotes of error messages, etc)
4. If possible provide an URL

Commenting on a JIRA Issue

Voting for a JIRA Issue

Watching a JIRA Issue

OFBiz JIRA Workflow

Epics are disabled - do we enable them?

Add a wiki page (if one does not exist) documenting:
  - Guidelines for writing JIRA mentioning clarity, provision of solution.
  - A clear definition of priorities (blocker, critical, major, minor,
trivial) with some examples.
  - A description of meaning of assignee and how to use it
  - A description of other metadata and how to properly use it (tags,
components, affects version, etc...)

TO TIDY UP - Copied from Committers Roles and Responsibilities page

Type of changes and where should they go

There are roughly 3 main types of changes:

1. New features
2. Improvements
3. Bug fixes

Bug fixes should normally go in the release branches, as much as they can. Security fixes must trigger a new released packages.
New features and Improvements should never get into a release branch. Exceptions may occur, but they need a consensus, and as ever can be vetoed (only by committers, though this rule can be adapted by the community)

All committers must do the following to ensure licensing compliance

1. Make sure the contribution is posted publicly on the Apache OFBIZ JIRA issue tracker. Please do not commit changes that were sent to you privately. If you receive a patch, open a JIRA issue and then ask the submitter to post his patch there. This way, we can avoid having to get an iCLA for the contributor, as well as let everybody in the community view and comment on the contribution.
2. If it is a new file, the file must have the Apache 2.0 license header.
3. The commit log must identify the name of the contributor and, if relevant, the JIRA issue for it.

Manage JIRA's issues

Please take the time to correctly fill the different Jira fields we now use for our releases change logs.

• Specifiy in Resolution :
  • Improvements : use either Done or Implemented Status as you feel right
  • New features : use the Implemented Status
  • Bug : use the Fixed Status
  • Of course you might also use other status (like duplicate, won't fix, invalid, etc.) when needed...

• Specify in the Fix Version/s the codebase(s) to which you have committed the patch/fix :

Temporary warning

Because we decided to not release the R14.12 and R15.12 branches, and because 13.07.03 was the last release of the R13.07 branch, currently only "Upcoming Branch" and Release Branches (like  Release Branch 15.12) are available in the "Fix Version/s" field. Not released versions (like 13.07.03) will no longer appear but when we wil release the next coming R16 branch.

• •  you can select from the dropdown one or more of the items under the "Unreleased Versions" group in the top part of the drop down box;
  •  you should never use one of the items in the "Released Versions"  section (bottom part);
  •  if the commit is only done (ie not backported) on "Trunk" then select "Upcoming Branch";
  •  if you are backporting/committing to a release branch then select the latest (next) release version in that branch available in the dropdown.

After some time the following Jira reports will contain very useful information :

• Road Map (what is expected in upcoming releases) : https://issues.apache.org/jira/browse/OFBIZ/?selectedTab=com.atlassian.jira.jira-projects-plugin:roadmap-panel

• Change Log (what is available in released packages available from the Download page) : https://issues.apache.org/jira/browse/OFBIZ/?selectedTab=com.atlassian.jira.jira-projects-plugin:changelog-panel

• Note about backports for bug fixes

When you don't backport a bug fix to a release branch, please explain the reason/s you don't backport. Then when others review they don't wonder why it was not backported and don't have to search why!

TO TIDY UP - Copied from Contributors Best Practices Page

How to create a Jira issue
 

1. Create an account here, if you do not have one
2. Login
   1. (optional if you are sure it's new) Search if an issue for what you are after already exists by using the "Find issues"
   2. (optional if you are sure it's new) If an issue on the subject already exists you can add a comment on it
3. If a issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
4. Select the OFBiz project and the issue type.
5. Fill in all fields, give as many detail you think necessary
   • Generally it is very important to select in the "Affect version" field the ofbiz version you are running. If you are running the trunk then the SVN revision should also be specifyed in the Environment field
   • Use the Environment field to specify at least your operating system and the database ofbiz is using since these information could be very useful to help people to work on the issue
   • Select the concerned component(s). If all components are affected select ALL_COMPONENTS (uncommon case)
6. If you need to attach files such as patches you must do it as a second step after the issue creation. It is also possible to easily attach screenshots to the issue see here
   • When attaching files or screenshots you can add a comment where you explain how the attached file is supposed to be used. Please reference the file name in the comment because more files could be attached to the issue at a later time and they will be all listed togheter far from their comments. If, for any reason, you don't want your patch or attachment to be granted to the ASF or committed, please note it in one related comment (possible cases: not ready yet, examples, etc.)
   • Also please use preferably .patch as extension for patches. When updating an attached file keep the same name : Jira is able to deal with that and will simply gray old files, you don't need to delete them (sometimes its usefull to compare older patches versions)
   • If you provide a patch, be sure to use the button "Provide Patch" (the status will then be "Patch Available"). This allows us (commiters) to know that this issue is ready for review.
7. Jira offers a voting mechanism that is used to give more relevance to the issues (see here to learn more)

When to create a Jira issue

1. Before creating any Jira issue, please check, using some related key words, if a similar issue does not exist already. For that you can first use the quich search at top right of Jira pages and after refine your search using relevant information. For instance by default all projects are scanned, you may then search only in OFBiz, etc.
2. If you already have a patch for an improvement/fix then create a Jira issue (if there is not one already) and attach your patch to it
3. If you don't have a patch, and you have discovered a bug, create a Jira issue (if there is not one already) providing as much details as possible (including the rev. number and the environment you are using, and the step to recreate the bug). if you have no ideas how to describe the bug use this template
   1. What you did (including detailed steps to reproduce)
   2. What you expected to happen
   3. What actually happened (including exact quotes of error messages, etc)
   4. If possible provide an URL
4. If you don't have a patch, and you have want to suggest an enhancement or new feature, then discuss this in the dev mailing list instead of creating a Jira issue; at the end of the discussion, the community will consider if a summary of the thread should be saved in a new Jira issue, to facilitate future development
5. If you don't have a patch, but you are planning to work on it, and you want to share your design details with the community, you should discuss this in the mailing list instead of creating a Jira issue; if, on the other hand, you don't have time to do this, you have already decided that you want to implement your patch following your design notes, and you just want to let the community know about the upcoming patch, you can create a Jira issue (to which you will attach your patch when it is ready);
   Summarizing:

• Bugs: always create a new Jira issue everytime you find a new bug
• New features/enhancements: create new Jira issue only if you have a patch (or if you plan to submit it very soon)

Editing comments in Jira

This feature should be used very parsimoniously because it's not easy to read edited comments from a mailing list and most people read comments from the dev ML (Jira issues are redirected to dev ML).
So, as far as it's possible, you should better add a new comment than editing one. If you really need to edit a comment, you MUST put a BIG prefix before your comment so it is possible to distinguish it from the original text. That should include more than just a pair of "*" to bold part or all of the response, and should also include your initials so that it is clear which things you added.

...