Guidelines for Using JIRA Draft Proposal 1

These guidelines have been created to help our community use JIRA effectively for Apache OFBiz development. These are the best practices that we want all contributors to follow. If you have a question, or something is unclear, then please don't hesitate to ask for help on the OFBiz development mailing list.

PLEASE NOTE: This page is a WIP

What is JIRA?

• JIRA is the tool that we use to track project related work. 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. 
• JIRA also provides a list of tasks that need to be actioned in the form of a To Do list, which can be sorted by a range of categories including priority, current status or the person assigned. It also can be used to generate statistics about work in progress and issue resolution.
• During our Community Days, JIRA's inbuilt agile functionality is used to manage the project backlog and create a Sprints for community members to work on.

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 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:

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.

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.

Also be aware that the JIRA labels are shared across all ASF JIRA projects so you will find labels releated to other projects in the drop down selection box.

To refine the use of labels it may be easier to define the ones that we want to use:

Do we have a list of labels that we could use and can we extract the existing list from Jira?

Reporter

The issue reporter is automatically assigned by JIRA based on the user profile of the person creating the Jira

Assignee

An Assignee is the person that is currently working on the JIRA issue. By default when an issue is created, the assignee is blank. Any OFBiz JIRA contributor can then assign themselves to an issue where the Assignee is blank. If an issue already has an Assignee then it means 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. 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

Component

The component field is used to identify which OFBiz component or application area is affected by the issue, The issue could be across all the applications or it could be restricted to a particular area such as Workeffort, Content, Datamodel or Accounting.

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

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.

Status

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

Affect Versions

Fix Versions

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. You need a JIRA account so if you do not have one then create an account here
2. Login to your JIRA account
3. 
   
   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
4. If a issue does not exist, create a new one selecting the "create new issue" command. For details on the issue creation see here
5. Select the OFBiz project and the issue type.
6. 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)
7. 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.

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