Issues workflow

Willhelm Rendahl edited this page May 24, 2015 · 2 revisions

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.

Triage queues

We have four triage (quadage?) queues that issues get placed into:

  • Support
  • ★☆☆
  • ★★☆
  • ★★★

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.

Support tickets

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.

Star tickets

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 information

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.

Operating System

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.

  • Linux
  • OSX
  • Windows

Issue type

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

Newbie friendly

The easy label indicates something should be easy enough that a new contributor to the project can reasonable tackle it.

Waffle-managed labels

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.

Closing tickets

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.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.