Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
The CKAN is a very popular project, and so keeping on top of issues can be quite a bit of work. Having our waffle board open while reading this guide can be valuable.
CKAN issues are assigned a number of labels, including criticality, sub-system, operating system, and whether it's a bug or a feature. While not every issue will include data on all these labels, we'll walk through the process of taking an issue from opening to closing.
Introduction to Waffle
Waffle provides an alternate view of github issues that makes it easier to keep on track of everything. While any user can view the waffle board, only CKAN collaborators can make edits using it. If you're a collaborator then you already have waffle access; just log-in (which will auth you via github) and go.
When tickets are first opened, they're placed in the backlog queue in waffle. Tickets in backlog are in need of triage. If you're not sure about an issue, you can always leave it in the backlog queue, but ideally you can move it quickly to one of the other queues.
We have four triage (quadage?) queues that issues get placed into:
To assign an issue to a queue, simply drag the card to the relevant column. When you do this, you should also consider amending the title of the ticket if it's currently unclear.
Of these, "support" is special. It represents issues which are user-support; questions which can often be answered with a referral to the FAQ, or which are vague in nature like "CKAN doesn't work". Support issues may represent legitimate bugs or enhancements, but primarily they're users asking for help with an individual problem.
These tickets may be reassigned into star tickets (see below) once we've gathered further information, but often these are answered and then closed.
Please respond to a support ticket when you drag it into the support queue; this establishes initial contact with the user. It also signals to our bots that we've responded; if the user doesn't respond back in seven days, the ticket is closed automatically.
The "star" based queues are based upon criticality:
- ★★★ tickets are critical. They're something which is in need of serious attention and affects a large number of users. These tickets warrant pulling developers out of whatever they're doing to fix.
- ★★☆ tickets are important. They represent serious bugs or enhancements, but we don't need to drop current work to do them.
- ★☆☆ tickets are nice to have. They're enhancements or bugfixes which affect a small number of users, or for which the workarounds are not particularly onerous.
When you drag a ticket into a criticality queue, you should ideally edit the title to indicate what work is required to close it. For example, "can't install mods while a cat sleeps on my keyboard" is a poor ticket name, whereas "CKAN should skip suggested mods when a cat is present" is a good ticket name.
Additional labels exist to provide more information about a ticket and what it relates to. Related labels are the same colour.
These are essentially sub-projects inside the main CKAN directory, and directly relate to code. They include:
- ckan.dll (the core)
- cmdline (the command line client)
- gui (the GUI client)
- netkan (the indexing client)
Not all ticket will relate to a sub-system, especially if they relate to meta labels below
These labels relate to processes that are relate to user code, such as build processes or architecture, and include:
- architecture - High-level architecture of the CKAN system. Eg: how should we store our registry?
- build - Our build systems, including how humans and bots build the code, release processes, and so on.
- infrastructure - Our helper bots, mirrors, and so on.
- policy - How we should handle particular situations, like two mods claiming the same identifier.
- spec - Changes to the CKAN spec, including new keywords or changes to existing ones.
If a bug or feature is only relevant to a particular OS, it should be tagged. If it's relevant to all systems, then don't apply an OS tag.
A lot of code-related issues fall into two neat categories:
- bug - Something that isn't working how we'd like it to
- enhancement - Something we'd like to do that doesn't exist yet
The easy label indicates something should be easy enough that a new contributor to the project can reasonable tackle it.
The following labels are applied by waffle, and should not be directly applied to a ticket:
- pull-request - Applied automatically to pull requests.
- in-progress - Applied automatically when waffle detects a branch that's working on the issue in question.
Tickets should be closed when we've provided the user with details to solve their problem, or if the user indicates a problem no longer exists (for support tickets), or when the work required to clear a ticket (eg: implement a feature or bug) has occurred (for other tickets).
The ideal way of closing code-related tickets is by using magic comments in git commit messages. Having a commit that includes the phrase "closes #1" would close the relevant ticket (in this case, issue #1) when that commit has been merged into master. This workflow has the advantage that tickets aren't kept open when their fixes have been applied.
In a very ideal world every git commit contains an issue number, so all work can be tracked and documented via the issue system, but we understand reality may differ from this ideal.