Tracking Issues with the Github Issue Tracker
The Github Issue Tracker is used to track bugs, feature requests, and other issues related to the Refinery Platform codebase. Issues related to particular deployments of the platform are discussed elsewhere.
- Search for an existing issue before opening a new one
- Include as much of specific information as possible in Github issues - if you can’t reproduce the bug, you won’t be able to fix it
- Don’t close issues until the solution is verified (all tests are passing and code review is complete); let the person who created the issue close it
The title should be a concise summary of the issue and either describe a required action, an observed problem, or a question. Here are some good examples:
- Longterm running CSS3 animated spinners cause drop of framerate.
- redirect user to analysis tab after analysis has launched
- Evaluate Django REST Framework as a replacement for Tastypie
- How to backup Refinery?
The description should be comprehensive and sufficient to allow another developer to understand what the issue is about. Code snippets should always use syntax highlighting. Use of (Github Flavored) Markdown is highly recommended. Related issues should be cross-referenced (using the '#XXX' syntax).
How to Report Bugs Effectively. A bug report should include the commit hash in which the problem was discovered as well as the following three sections:
- Steps to reproduce: detailed instructions on how to reproduce the problem.
- Observed behavior: a description of the problem. Relevant log messages and/or screenshots should be included (do not use screenshots for text: image content is not searchable). For Macs, GifGrabber is a popular software to make gifs, which can be helpful in showing observations.
- Expected behavior: a description of what should have happened. If the source of the problem is known or suspected this should be discussed as well.
Features provide new functionality that does not yet exist in the software. Enhancements improve existing functionality and can relate to both usability and system performance. For complex new features task lists should be provided used.
Technical debt issues describe required updates of external libraries and tools, need for code refactoring, and other maintenance issues that (ideally) have no effect on the user experience. Links to external software should be included if relevant.
Questions typically fall into one of the following categories: votes, discussions, or requests for comments. The issue tracker is not intended for development related questions ("How do I do X?"), those should be posted in the Slack chat. Note: The individual creating a "question issue" should assign the issue to themselves and close the issue once the question has been answered.
Labels are used to organize issues and to provide an overview of the state of the codebase. They are also intended to help with the identification of relevant issues during the planning meeting. Depending on the goals of the next development cycle, relevant issues could be related to a particular component of Refinery (e.g. import or visualization), they could be of a particular type (e.g. bugs or technical debt) or related to a particular layer of the system (user interface, API, etc.), therefore different label "dimensions" are used to annotate issues: type, layer, and component. Additionally, labels can be used to assign a severity to an issue or indicate the involvement of external tools or libraries. These modifiers are optional and used to prioritize and assign issues to developers.
We use the following 4 labels to aid in estimating the relative size of issues: quick-fix, small-fix, medium-fix, large-fix.
As far as relative sizing goes, these labels are each twice the size of their predecessor.
New issues should be assigned to the Next milestone to ensure that they are discussed in the next planning meeting.
Assignment to a developer is optional.