The following guidelines assist with knowing what to report, and how to create and manage issues.
Sign up for an account
To create issues or add comments, sign up for an account via the front page. (This is also used to manage accounts for wiki.folio.org, so same account for both.)
Report various issues
What types of issue does the project want to hear about?
Anything that you find confusing, does not work as expected or as documented, specific bugs, problems, feature requests, obscure messages or behaviour. Also tasks that the teams know should be addressed at some time, now or later.
FOLIO aims to provide useful descriptive error messages in the relevant situations. Please assist that by reporting when a particular message is not fully relevant or could be enhanced.
Preparing to add an issue
Review the “which forum” guidelines to be sure that adding an issue is the appropriate action.
Describe the issue concisely in the Summary and Description fields. Use Comments for further detail. The Summary and Description are also utilized for reports and for every notification email, so detail is better in Comments.
Use the Search facility to ensure that an issue is not already reported, or has perhaps resurfaced and so can be further described.
Be careful not to speculate too much about the causes of the issue.
Provide the facts, describe your actions, the expected results, and actual results as clearly as possible. That time spent does help everyone.
Use a local text file and your familiar editor to prepare and save the summary, description, and comments. When ready then copy-and-paste.
Jira uses a particular markup language for special formatting, and is different to GitHub etc. There is a link to Jira help via its “Add Comment” screen.
Use attachments for long log files, text listings, and images. Be sure to redact information that would compromise privacy.
When creating the issue, select the most relevant Project and the Issue Type (see below for definitions). Each individual source code repository’s README document has a link to its particular issue tracker Project. If unsure which Project, then use “FOLIO”. Someone can change these later if necessary.
For the “Bug” issue type, use the “Configure Fields” option to add the Environment field.
After issue creation, use follow-up Comments for further detail. Attachments can be added later.
Unfortunately Watchers cannot be added on issue creation. So use the technique of a concise Description when creating, then immediately add Watchers, then follow-up Comments will notify them. Another workaround is to add people using the “@mention” facility (type “@” then any part of their name). They can then choose to add themself as a Watcher.
Someone else will later determine the Assignee and the Priority, and will link between relevant issues.
Each Project uses the following Issue Types:
- New Feature: Some new functionality request, yet to be developed.
- Bug: A defect which impairs or prevents proper function, and can usually be resolved without changing the functionality of the system.
- Task: Some job that needs to be done, usually not directly related to product code changes.
- Sub-task: We try to avoid this, and instead use other types, and then Link between issues.
- Umbrella: This type is used for project management. Please use one of the other types.
The priority level indicates the importance to the dev team. An Issue Priority is set by the project managers.
- P1: highest priority item, drop everything else before this is resolved, reserved for critical bugfixes
- P2: high priority level, must be included in the current development cycle
- P3: normal priority level, item will be considered for inclusion in the next dev cycle
- P4: low priority level, nice-to-have things that require future discussion and design
Note that the priority might not match the severity felt by the issue reporter. That is better represented by other means (such as the number of watchers or votes) and by providing clear Comments about the issue and its impacts.
After creating the issue with a concise Description, follow up with more detail in additional Comments.
When other people comment and ask for clarification, then try to respond promptly. We all like to keep the issue resolution process moving smoothly.
If comments start to turn into a lengthy discussion, then follow up in other forums, and then summarise into further issue tracker Comments. Provide links in both directions.
We use the following workflow:
- Open: Ready for the assignee to commence work on it.
- In Progress: Being actively worked on at the moment by the assignee.
- Reopened: The resolution was incorrect, or subsequent developments have caused the issue to resurface.
- Closed: Finished.
The Status does not preclude other people from assisting. Please add relevant Comments.
Other people will create tracker Links between relevant issues.
Using an Issue identifier within text Comments will automatically link to
Note that it must be upper-case.
Using such an issue identifier in git commit messages and pull request titles, will also automatically link the Issue to the commits.
Provide other relevant bi-directional links, for example GitHub pull requests and Discuss topics.
Filters and search
Various issue Filters are available via the “Issues : Search” menu. For example, the “Added recently” and “Updated recently” filters help to be aware of recent action.
Create your own filters. Use one as a base, then twiddle and Save As.
There are some example filters at Manage notifications to keep abreast.