Create sublime text plugin support both ST2 and ST3

Question

I made a couple of plugins for Sublime Text 2, but when Sublime Text 3 came out, it had a new Python engine, and my plugins stopped working. I managed to fix them, by debugging all the issues one by one, but now I have two versions. The original installs from Package Manager smoothly, but the new one can only be installed from the branch of code I put it on being checked out from git.

How should I properly manage a plugin for sublime text to support multiple versions?

Are there any blog posts about how to do this effectively?

Answer 1

You can manage two different code branches for different builds of Sublime Text. If you take a look at example-repository.json around line 200 and following, you'll see this example:

// If your package is only compatible with specific builds of
// Sublime Text, this will cause the package to be hidden from
// users with incompatible versions.
{
    "details": "https://github.com/wbond/sublime_alignment",
    "releases": [
        {
            // This branch (default: "master") is for Sublime Text 2.
            // Remember: The sublime_text key is required!
            "sublime_text": "<3000",
            "details": "https://github.com/wbond/sublime_alignment"
        }
        {
            // This branch ("st3") is for Sublime Text 3 (and above).
            // You can specify as many releases as you want.
            "sublime_text": ">=3000",
            "details": "https://github.com/wbond/sublime_alignment/tree/st3"
        }
    ]
},

This way, if you have different code bases for the different versions of ST, or even different builds of ST3, if you depend on some API change that was only implemented in a certain build, the end-user will seamlessly get the version of your plugin you want them to.

It may not be possible, depending on how you use the API, but perhaps in the long run it would be easiest to harmonize your code between ST2 and ST3. If you need to use some advanced feature, you can always use this type of construct:

if sublime.version() >= 3000:
    do_advanced_stuff()
else:
    do_st2_stuff()

to split up your code and fail gracefully, and it may be in some circumstances that certain plugins running under ST2 just won't have the functionality they'd have if ST3 was being used.