Plugin Versioning

Recently, I had some users of the event plugin have a misleading impression of the plugin due to its version 0.1. I don’t know if thats the case with other plugins, but I think we should decide on a strategy to systematically bump the plugin version to give users especially the new ones a sense that our plugins are quite mature.
@members. What say…?

Here’s an interesting wikipedia article about that.


Yeah I think that’s good.
If a plugin has core functionality that works bug free in production sites should probably just be 1.x?


@fzngagan I love that you started this topic. Yes this is definitely something we need to do. This and tests.

Let’s make this a #open-source:projects actually. We need to cover:

  1. Our versioning policy. We need a single policy we use across all projects
  2. Use of required_version in metadata (see lib/metadata.rb - we don’t use this at all currently)

@fzngagan If you could lead this project that would be fantastic. That means:

  1. Laying out what our policies for the above are in some detail
  2. Getting the plugin maintainers (i.e. Myself, @merefield and other maintainers we bring onboard) to buy in and adopt the system.
  3. Fielding any questions or issues with the system.

This shouldn’t take priority over your more pressing items, but it could be something to work on a little bit each week.


Sure man. I would love to. It’ll be really interesting. Its a process actually and eventually we’ll come to conclusion about a flexible yet rigid enough versioning policy.

Sure. I’ll make sure its on the correct priority.


@members, I’ll take some time this week and share my important findings on this. Also, feel free to nudge me for this in future.


Great, looking forward to it!


This is a super cool document that explains the semantic versioning specification. I suggest we should go with this way of versioning plugins. The whole idea is to convey the state of your software by version numbers. I’ve condensed the document to a few points which we need to care about the most and for further details, you guys can go to the site and read the full spec. I’ve included some points from faqs due to their relevance.

  • The basic format is MAJOR.MINOR.PATCH . This means that bugfixes should increment the PATCH digit, small features should bump the MINOR digit, and an overhaul :wink: or something which changes a lot of previously built stuff (backward-incompatible changes) should bump the MAJOR digit.

  • The initial release should be 0.1.0.

  • If there is a major release, the minor and patch versions will be reset to 0. i.e. if a major release occurs after 1.4.7 it would be 2.0.0.

  • No changes should be introduced to the released code after release.

  • A pre release version should be denoted by appending a hyphen to the actual version. i.e. 1.0.0-alpha 1 etc.

  • The major version will be bumped even if a small backwards incompatible change is introduced to the codebase. My suggestion personally would be not to do that in the first place and instead, create a new major release branch, add more changes and release the version once a substantial set of features is introduced.

  • The spec should be strictly followed in order to get the benefits it promises.

  • The version should be bumped to 1.0.0 if your software is already running in production.

Backward incompatible is a concept which I’m trying to comprehend in the context of Discourse plugins. Any thoughts on this are super welcome…


@fzngagan Great! Can you give us an example with the events plugin? What version do you think the plugin shoudl be at and how does recent work you’ve done fit into the sematic versioning scheme?


Ha versioning. I think most of us know this, but because it is not automated nor of systematic importance it gets overlooked.

Also there is at least one more convention:

  • early release that is not feature complete = alpha but feature complete but not fully UAT’d and bug free = beta?

Formally, alpha is the one which is tested positively by the dev themselves and beta is tested positively by a closed set of users so yeah both need to be feature complete I guess.


This is a damn good point. It would be great if at least the PATCH version bumps were automatic. Knowing when a MINOR and MAJOR bump is required is too complex to automate IMO.

If you were going to automate PATCH bumps, what would be the hook for that?
Bump on every save operation (ridiculous number of bumps possibly)
Bump on every git commit?
Bump on every PR?

1 Like

Alpha’s are in reality rarely feature complete though

1 Like

In practice, that might be the case actually. I’ll rephrase it as, looks complete to the dev. Thats when the work starts lol :wink:


Haha. Yeah


I’m packaging a trivial Ruby Gem today (something unrelated to Discourse) and I found there’s a gem for bumping Gem versions, which has templates and assists with semver conventions. Just thought I’d flag it in this thread, in relation to plugin versioning.

Even if it’s not directly applicable to our plugin development workflow, there might be things we can take from it that we could implement, eg some degree of automation of version incrementing.

here’s an example of the output when I bumped the version

gem bump --version minor                      

Bumping flat_json_unflattener from version 0.1.0 to 0.2.0
Changing version in lib/flat_json_unflattener/version.rb from 0.1.0 to 0.2.0

Staging lib/flat_json_unflattener/version.rb
$ git add lib/flat_json_unflattener/version.rb

Creating commit
$ git commit -m "Bump flat_json_unflattener to 0.2.0"
[master 90fbee0] Bump flat_json_unflattener to 0.2.0
 1 file changed, 3 insertions(+)
 create mode 100644 lib/flat_json_unflattener/version.rb

All is good, thanks my friend.
1 Like

Some fresh thoughts on this.

I think we can choose one of the two paths from these(you guys may suggest more)

Method 1 :- This accounts for accuracy. What we can do is, simply go through all the PRs that were made to the plugin in question, and bump the minor version per PR and the major where we have to do a migration(migration is a pointer towards breaking changes).

Method 2 :- This accounts for simplicity. We’ll simply check from which PR was the plugin good enough for Production use. We’ll call it 1.0. Then, follow Method 1 for minor version and breaking changes.

These are my suggestions and I hope this brings us closer to our goal of versioning our plugins. Thoughts?

1 Like

I sort of feel we should consider functionality too:

  • Major new feature is bump of major version, e.g. introduction of Tiles for TLP was a massive change.
  • Medium new feature bumps to 0.5?
  • Small new feature bumps +0.1 (medium change)
  • Minor feature +0.0.1?

Major refactor for change in core, yes Major version +1

I think your PR suggestion is good, and in addition I think we should consider functional change as just or more important?

However, rather than over-doing it and going into huge back detail, I would simply try to identify the big historic functional (and perhaps technical) changes, and give each a + 1.0.0 then work out the more detailed history (the medium level since the last major change), then any patch.

This should cut down the work involved and still let us arrive at a sensible number?


Additional to what you said @merefield, We also discussed in our last call to bump to 1.0 when test coverage approaches >80%. thoughts?

1 Like

2 posts were split to a new topic: Breaking changes