Recent discussions in hip chat and in JIRA exposed it'd be good to have a well defined policy describing best practices related to reporting issues by users. Below I typed proposed narrative, comments / improvements are welcome.
This RFC should be implemented by incorporating this text into one or both of pipelines.lsst.io and developer.lsst.io.
Recommendations for filing a new issue:
- Project: DM
- Issue Type: use the "bug" or "improvement" issue type. The former should be used to report flaws / failures, the latter should be used to request an improvement or a new feature
- Summary: short description of the issue
- Priority: make a guess, or leave default. Use blocker or critical for truly blocking issues.
- Component: set it if it is obvious. Do not create new components (request needed components from a JIRA admin)
- Fix Versions: leave empty
- Assignee: set to "Unassigned"
- Watchers: leave empty, or add developers that you'd like to be alerted about your issue
- Description: type the description, paste relevant error messages, snippets from log files and anything else that you think may help us understand the issue. This might include things like operating system (and browser, if web-based); eups setups (eups list -s); input data; the command that's producing the issue; the actual output from that command; the expected output from the command etc.
- Story Points: do not set it, leave it for the domain expert to make the assessment
- Linked Issues / Issue: leave blank
- Epic Link: leave blank
- Sprint: leave blank
- Team: feel free to set it if you know which team it falls into
I wonder if most of this content is already in the dev guide: https://developer.lsst.io/processes/workflow.html#creating-a-ticket
That was added with
DM-4412, although the emphasis is a bit different. The current instructions are how to deal with JIRA for your own work, whereas this RFC is how you file a bug report on something that you are not directly working on.
Yes, I think there's value in having a playbook for this aspect of JIRA reporting.
I've been thinking about how to re-organize the Developer Guide to be more effective. One thing I've been thinking about is exploding things like https://developer.lsst.io/processes/workflow.html so that specific subject (creating a ticket, branches, code reviews) are in dedicated pages, but still bound by an overview document. I've started thinking about this re-org in
Jonathan Sick Developer workflow was very helpful for us. One little suggestion: Make a short set-by-step cheat sheet for developers to reference. Sometimes a reminder is enough without reading through all the detailed documents.
It's mostly DM staff given that you need a JIRA account to file an issue. Of course, as time goes by we'll get more people outside DM trying things out but I assume we punt worrying about that until we know what operations would look like. At least if it exists in developer.lsst.io we can easily point others at it.