Issues workflow

The CKAN is a very popular project, and so keeping on top of issues can be quite a bit of work.

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.

Triage queues

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

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

To assign an issue to a queue, add the relevant label. 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 add it to 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 bug fixes which affect a small number of users, or for which the workarounds are not particularly onerous.

When you add a ticket to 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.

Sub-systems

These are essentially sub-projects inside the main CKAN directory, and directly relate to code. They include:

• ckan.dll (the core)
• GUI (the GUI client)
• ConsoleUI (the interactive console UI)
• Cmdline (the command line client)
• Netkan (the indexing client)
• Tests (the unit tests for all the other sub-systems)

Other labels concerning mainly coding:

• Documentation - code documentation or wiki related.
• Network - everything regarding communication of the ckan client with the internet.
• Registry - the part where ckan saves all metadata infos for available and installed mods.

Not all ticket will relate to a sub-system, especially if they relate to meta labels below

Meta-systems

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.
  • Cake
  • Debian-package
  • AutoUpdate
• Infrastructure - Our helper bots, mirrors, and so on.
• Relationships - How to deal with dependencies, recommendations, suggestions, incompatibilities and replacements
• 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.
• Schema - Updates to / problems with the Schema that netkan files are validated against.

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
• OS X
• 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. Also feel free to bring in your opinion especially in Discussion needed labeled issues/PRs.

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 or pull requests. 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.