One of the most important aspects of the Blaze project is the issue management on the official Blaze Bitbucket page. We cordially invite all Blaze users to submit feature requests and bug reports, as we believe that this is a significant part of making Blaze a better library. However, we are asking to follow a small set of guidelines when creating an issue to facilitate the issue management on our side and also to make issues more useful for users of Blaze.
The title is the most important detail of an issue. A well chosen title makes it easy to grasp the idea of an issue and improves the discoverability. Therefore, please choose a title that is ...
- ... as descriptive as possible;
- ... as concise as possible;
- ... as unambiguous as possible.
Also, please create a separate issue for each idea/problem/etc. A very general title or an "and" in the title could be an indication that the issue is not specific enough and should be split into several issues.
- "Provide support for AVX-512 SIMD operations"
- "Add support for the Boost Multiprecision Library"
- "Introduce reduction operations into Blaze"
- "Compilation error on KNL with -march=knl"
- "Several requests" (instead create separate issues for each single request)
- "Improve the performance" (instead specify which operation should perform better)
- "Blaze library compilation error" (instead try to be more specific)
The description should help us to understand your idea or problem in as much detail as possible. Also, it helps to clearly spell out your expectations (how a feature is supposed to work, how the behavior should be, etc.). Please spend a couple of minutes to try to make the description as comprehensive as possible.
There is no need to assign the issue to a particular person. It is perfectly ok if you just ignore this setting.
Kind of Issue
There are four kinds of issues available in the Bitbucket issue tracker: Bug, Enhancement, Proposal, and Task. In the following we try to give guidelines on which kind to choose for a particular issue:
Please choose the category Bug if ...
- ... you experience a compilation error despite your best efforts to get it right;
- ... you experience a crash/failure despite your best efforts to get it right;
- ... you experience problems when combining features;
- ... a feature does not work as specified/documented (i.e. can be considered broken).
Please don't choose the category Bug if ...
- ... you feel a feature should work differently than it currently does (instead create a Proposal with a convincing title and description);
- ... you are not sure how to use a feature (instead create an Enhancement issue to extend the documentation);
- ... you are missing a feature (instead create a Proposal or Enhancement issue).
If you select the category Bug, please also try to provide a minimum example that fails. That helps us to minimize the time to resolve the bug.
As we try to keep Blaze bug-free, we will always prioritize bug issues. However, we will also quickly close bug issues as "wontfix" if the described issue is not a bug (i.e. one of the problems mentioned above). We will not relabel a bug issue to Enhancement or Proposal, even if they would be reasonable extensions to Blaze.
Please choose the category Enhancement if ...
- ... you need an add-on to an existing feature;
- ... you need an extension of an existing feature;
- ... you need an extended documentation for an existing feature.
Please choose the category Proposal if ...
- ... you want to request a new feature;
- ... you want to change an existing feature.
Please choose the category Task if ...
- ... you want us to do something not feature related;
- ... you have something else in mind which does not fall in the other three categories.
Via the priority of an issue you can tell us how important the issue is to you. Therefore the priority can have an influence on when we will deal with the issue. However, unfortunately we don't have an infinite amount of time and we can not deal with an arbitrary amount of issues at the same time. We will therefore take the priority into account, but mainly schedule the issues based on impact to all Blaze users and the estimated time to resolve it.
Please choose a Blocker priority if ...
- ... you cannot work with Blaze due to the described Bug;
- ... the Bug likely has an influence on all Blaze users.
Please choose a Critical priority if ...
- ... you can work around a Bug, but the workaround is (much) slower or awful;
- ... you cannot use Blaze without the proposed feature;
- ... you consider it to be essential for all Blaze users.
Please choose a Major priority if ...
- ... a Bug or feature request is not Critical, but still very important to you;
- ... you consider it to have a Major impact on most Blaze users.
The Major category is the default setting in Bitbucket and we therefore consider it as the default priority for issues.
Please choose a Minor priority if ...
- ... a Bug does not affect many Blaze users;
- ... a feature request would only be useful for a small number of Blaze users;
- ... a feature would be nice to have, but is not particularly important.
Please choose a Trivial priority if ...
- ... a Bug hardly affects anyone;
- ... a feature request would only be useful for very few Blaze users;
- ... the expected time to resolve an issue is very small.
You can always provide us with additional information in the form of attachments. Feel free to attach something to the issue if ...
- ... it can help us to analyze a Bug;
- ... you have some source code that demonstrates a problem;
- ... you already have a working prototype that sketches the idea;
- ... you have additional resources that could help us.
We appreciate anything that simplifies our work and speeds up our progress.