[ckan-dev] Extensions supporting different versions of CKAN

Mon Aug 12 17:12:30 UTC 2013

Hey,

I'd like to propose an alternative way to specify what branch of an
extension should be used with a given branch of CKAN.

The current policy is explained here:

http://lists.okfn.org/pipermail/ckan-dev/2013-May/004824.html

> When installing an extension, developers should always use the
> "stable" branch [of the extension], unless there is a specific branch
> that targets the CKAN core version they are using.

i.e. if the extension has a branch called release-v2.1 and you're using
CKAN version 2.1, you should use that branch of the extension not the
stable branch (and presumably CKAN versions 2.1.* should use that branch
as well).

But honestly I don't think this is a workable policy, and I'm having
trouble explaining it in the writing extensions documentation.

Problems:

- If an extension is developed during the CKAN 2.2 days and has a stable
  branch that supports 2.2, then some breaking changes are made in CKAN
  and released in CKAN 2.3, then according to the policy above the
  extension's stable branch should work with CKAN 2.3 but in fact it
  doesn't.

- What happens if an extension has branches master, stable, and
  release-v2.1, and I'm using CKAN 2.0?

- What if an extension has branches master, stable, release-v2.2 and
  release-v2.0 and I'm using CKAN 2.1?

- Every time you commit on master you're then going to have to
  cherry-pick that commit onto stable and potentially onto release
  branches as well

- No way for an extension to clearly indicate which versions of CKAN it
  does and doesn't support

Maybe instead we add a paster command to all extensions. If you want to
know what branch of an extension you should use with a given CKAN
branch, you run the extension's `paster branch` command:

    $ paster --plugin=ckanext-spatial branch release-v2.0
    master

this means that with CKAN branch release-v2.0, you should use the master
branch of ckanext-spatial.

This way we don't have to come up with a branching policy for extensions
that covers all cases and doesn't have any disadvantages (like requiring
too much branching and cherry-picking). Each extension can just define
its own.

Also it's good for scripting, if you were for example writing a CKAN
install or upgrade script, it can ask each extension which branch it
should check out.

You should always checkout the master branch of the extension and pull
the latest commit, before running the `paster branch` command.

We'll change the template extension that the
`paster --plugin=ckan create -t ckanext ...` command creates to include
a default version of this paster command that always returns 'master'.

Extensions can then modify the function to do whatever they want. This
function should always be pretty simple, e.g.:

    def branch(ckan_branch):
        if ckan_branch == 'release-v2.2':
            return 'release-v2.2'
        elif ckan_branch in ('release-v2.1', 'release-v2.0'):
            return 'release-v2.1'
        elif ckan_branch == 'master':
            return 'master'
        else:
           raise Unsupported

Raising an exception and exiting with non-zero exit status means the
given branch is not supported.