ICEsoft JIRA Issue Creation Guidelines

Welcome to our guidelines regarding creation of ICEsoft.org JIRA issues.

JIRA issues are central to the development processes for all our products. We get issues submitted from many different sources: from inside the development teams, from customer advocates, and of course directly from customers. We greatly appreciate you taking the time to submit issues, as your feedback helps us to continually improve our products.

Filing effective issues is incredibly important. Every product has a lot of issues logged in JIRA, and many more get filed each day. The more accurate details there are in each issue, the more efficiently we can deal with it, and the more likely it is that the issue will be resolved sooner. The following steps will assist you in filing effective issues.

Did you come to the right place?

We maintain this instance of JIRA to track improvement requests and reproducible bugs. This instance of JIRA is not optimised for questions and problems, for these types of inquiries please refer to the appropriate ICEsoft.org Forum. Alternatively, we employ a team of highly specialized support engineers who will gladly help you with problems, usage questions, etc. under a suitable commercial Support Agreement. They can look at your specific environment settings, analyse your logs, and dig deep into your issues.

Search for duplicates

With thousands of customers, and a huge collection of improvement requests, new features desired, and bugs reported, chances are that your issue has been logged already.

Before filing a new issue, try searching within the relevant project for some of the key words in your issue. Or, if you can identify the relevant component (e.g. "Attachments", or "WYSIWYG editor"), try drilling down on the issues found there.

If you find that someone else has already filed a very similar issue, vote for the existing issue instead of creating a new one. You can also add a comment to the issue, if you have some information that would help us resolve it faster or can describe the issue in more detail.

Don't reopen issues that have been resolved and shipped

Please don't reopen resolved/closed issues once they have been shipped. If an issue similar to yours is marked as resolved, but you're still experiencing a problem with it, please create a new issue and provide a link to the original one. In the case of resolved bug-fix-issues, this will help us evaluate whether it is in fact the same problem, or actually a new issue with some of the same symptoms. In the case of resolved feature-issues, it is better to raise a bug-issue and link back to the feature-issue, and let us decide if we really want to reopen the original feature-issue as well.

Choose the appropriate project

Each of our products has its own JIRA project. Please file your issue in the project that matches the product you are using.

Is it a Bug? Or a Feature Request?

When filing a new issue, you will need to select one of the following issue types: "Bug", "Improvement" or "New Feature". Sometimes it can be difficult to differentiate between these three concepts. After all, fixing a bug means improving the product, and adding a new feature is certainly an improvement too.

Bug

A problem which impairs or prevents the functions of the product. If the product behaves differently from what was expected, that is a bug. If something should happen, but doesn't, that is a bug too. Write the summary of a bug in the following format: "Function X produces error Y when doing Z", or "Function X does not produce result Y though doing Z". If you can't write a short sentence similar to these, you are most likely not reporting a bug.

Improvement

An enhancement to an existing feature. An existing feature or function of the product works as advertised, but you would expect more from it. For example, "Function X should work faster when doing Z", or "Function X needs to do Y in order to make working with ICEmobile more efficient".

New Feature

A new feature of the product. This is a request for adding significantly new portions of functionality to the product. Write the summary like this: "Add a new X Component", or "Create new feature X to enable Y".

Pick a good summary

When we're looking through lists of lots of issues, the summaries are essential in helping us to understand what an issue is about. This means that you should err in favour of putting too much information in the summary, rather than too little. Some examples:

Bad: Chart export doesn't work
Good: Chart export fails with JavaScript error on IE7/8
Bad: dataTable paginator control
Good: ace:dataTable: Allow configuration of number of rows per page in paginator

Write a detailed description

When filing a Bug

There's a very simple, universal formula for bug reports. Every bug report must include:

1. Detailed steps to reproduce
2. What you expected to happen
3. What happened instead

The steps to reproduce should be written in terms that anyone could follow: "Create a new Confluence page called 'Test'. Insert the following text: 'bq. I like cheese'. Set page permissions to 'Me'. Click the 'Save' button."

When filing an Improvement or New Feature request

Detail, detail, detail, context, context, context.

Tell us why you want the feature, as well as what it is. If the request comes from an email or IM exchange between co-workers, consider pasting that into the issue too!

Knowing why somebody wants something done is almost as important, in terms of scheduling and planning features, as knowing what they want. Sometimes it's more important, because often by knowing why somebody wants a certain feature, we can deliver a better solution than they'd even thought of, or we can aggregate a bunch of related requests into an über-solution that makes everyone happy.

Always choose a component

Every JIRA issue can be placed in one or more components. Most issues belong to one or two components; more than three should be avoided. The component is the second most important part of the issue after the summary, in terms of helping us quickly understand what the issue is about.

If you can't find an appropriate component for your issue, please pick the closest one that almost matches.

Set the "Affects version"

When reporting a bug, please select the version of the product you were using where you encountered the bug. This helps us track down the bug, and it also helps us identify who else might be affected by it.

If you are using version 3.1 of a product, please select just 3.1 (not 1.8, 2.0, 2.0.1, 3.0 and 3.1). If you know and want to point out that a bug already existed in 1.8, and still occurs in version 3.1, then please select 1.8 and 3.1, but not all the others in between.

Don't set the "Fix version"

Please do not select a fix-version. We will schedule the issues as appropriate.

Use images

Often, especially when describing bugs, an image will help tremendously to explain the issue. Once your new issue has been saved, you can easily attach a screenshot in just a few seconds — you don't have to save your image as a file and then upload it.

Link issues

If you know that a feature request is similar (but not identical) to an existing one, please link it using a link type of "relates to". Or if a bug seems to be related to another one, please link them as well, even if you are not 100% certain. This will help us when we start working on your issue because we get a broader view of the problem, and may be able to solve not only one but two issues. And if the links turn out to be irrelevant, we will just remove them — no worries.

Set the priority

We have five priority levels. You can set an initial priority on the basis of how the bug affects you. Please use this list as a reference

• Blocker: Server crashes and deadlocks for major configurations, users can't work properly. Examples of blocker bugs:
  • "After including icefaces-compat.jar on the project classpath, the application crashes"
  • "The server deadlocks when more than 500 users log in"
• Critical: Crashes, loss of data, severe memory leaks. Examples of critical bugs:
  • "After editing a value in the ace:textEntry component, all ace:textEntry components in the same form change to the edited value."
  • "After an ICEpush update is received by the browser, the page goes blank"
• Major: Major loss of function. Examples of major bugs
  • "Using an ice:selectInputText inside an ice:tab results in JavaScript errors"
  • "When exporting an ace:dataTable to a PDF file some rows are missed"
• Minor: Minor loss of function, general annoyance, or other problem where easy workaround is present. Examples of minor bugs:
  • "Draggable ice:panelPopup sticks to pointer in IE"
  • "When exporting an ace:dataTable to a .xls file, some blank rows are inserted at the top of the document"
• Trivial: Cosmetic problem like misspelled words or misaligned text. Examples of trivial bugs:
  • "The German translation of 'label' is incorrect"
  • "The ace:autoCompleteEntry popup list is offset from the input component by 30px in IE7"
    We may increase or decrease an issue's priority in accordance with the relative priorities of other issues.

Adapted from the Atlassian Confluence JIRA Guidelines.