Plugin Developers!! Read this re: v0.6.0 Breaking changes

  • GNU/Linux Admin

    Hey all,

    Re: The breaking changes outlined here:

    It is important that your updates to your plugins are not published to npm until the following steps are taken (in this order):

    • If you have any plugins already published with fixes for v0.6.0 (otherwise skip this):
      • Unpublish them now
      • Create a branch that branches out from the last v0.5.x compatible commit: git checkout -b somethingunique {commitHash}
      • Add a property to package.json called nbbpm with the following Object: { "compatibility": "^0.5.0" }, or whatever the compatibility hash your plugin is already using
      • Commit and publish this as a new version to npm
    • While your plugin is compatible with v0.5.x:
      • Remove the compatibility or minver property from plugin.json, it is now deprecated. Remember the old value.
      • Add a new property to your plugin's package.json called nbbpm. This property contains an object with the property compatibility. This property points to a semver-compatible string stating the plugin's compatibility with NodeBB. If you know your plugin works against v0.5.2 only (but not v0.5.1), then the string you should use is ^0.5.2
      • For reference, this is what it looks like:
      "nbbpm": {
        "compatibility": "^0.5.0"
    • Publish this to npm as a new version
    • Make the appropriate changes to comply with v0.6.0's changes
    • Change the compatibility value in package.json to now read ^0.6.0
    • You're done!


    The reason behind this is simple: We want to stop plugins from becoming incompatible as they are updated against newer versions of NodeBB. npm tends to assume you want the latest version when you run npm install packagename, so we are building a system for v0.6.0 (that will be backported into v0.5.x) that queries the NodeBB Package Manager and requests a version given the installed NodeBB version.

    You can see it in action here:

    This way, even when your plugin is updated to v0.6.0, and breaking compatibility for v0.5.x versions, those NodeBBs will still be able to install plugins via the ACP, they'll just install the lower version that is reported (by you!) to be working.

    Please let me know if any of this is comfusing, and I will try to explain better πŸ˜„

  • GNU/Linux Admin

    Compliance with this new standard is optional. We couldn't possibly force everybody to use it.

    If you don't, then older NodeBB versions will install the latest plugin version and possibly break the NodeBB, like it does currently.

    Grand scheme of things, we'll also use the package manager to allow users to vouch that a plugin works with a specific version, and that'll tie in with the suggestion engine as well. But that's far off right now πŸ™‚

  • So, to summarise, add nbbpm compatibility to current version that the plugin supports, publish that to npm.
    Make changes for 0.6.0, update nbbpm compatibility to 0.6.0, but don't publish? Or do publish? πŸ˜†

    As the nbbpm hasn't been backported yet, has it?

    Either way, things are certainly coming together in terms of plugin compatibility. So kudos. πŸ˜„

  • GNU/Linux Admin

    I do have a propensity for verbosity, don't I. @psychobunny and @baris keep saying that (maybe not in those words) XD


    Edit: But yeah, don't publish the v0.6.0 ready version yet. Give me a couple hours.

  • @julian said:

    I do have a propensity for verbosity, don't I.


    an inclination or natural tendency to behave in a particular way.


    the fact or quality of using more words than needed; wordiness.

    Yes. πŸ˜†

  • GNU/Linux Admin

    Hey guys,

    gh#2363 is pushed and backported to v0.5.x, you may begin making changes to your plugins πŸ‘

  • Plugin & Theme Dev

    Now I need to update all those plugins of mine πŸ˜•

    I'll be done somewhere around Christmas with my current free time πŸ˜„

  • @Schamper When you've done yours, I'm accepting PRs for mine. πŸ˜†

  • Wouldn't this topic be better off in a public category, not every plugin developer might be subscribed to the dev group

  • @psychobunny I thought this category was only available to people in the dev group. Probably not very useful for people like shard, that are developing plugins, but can't see this topic for example.

  • GNU/Linux Admin

    Probably XD. Let me move it there now.

  • @julian said:

    I do have a propensity for verbosity

    you just summed it all up yourself πŸ˜›

  • Plugin & Theme Dev

    I understand the new concept but why unpublish first?

  • GNU/Linux Admin

    Upon reflection, the unpublishing step is unnecessary

  • Plugin & Theme Dev

    I wonder, is it necessary to make a new branch too?
    npm wouldn't just store the commit on master branch?

  • Plugin & Theme Dev

    My bad, I didn't see it was for already 0.6.0 published plugins.

  • GNU/Linux Admin

    I correctly assumed (and this has been validated through actual plugin upgrades) that the latest hash in npm points to the most recently published version, and not the highest version.

    That is, given your plugin nodebb-plugin-example

    • If v1.0.0 is compatible with v0.5.4
    • If v1.1.0 is compatible only with v0.6.0
    • The latter is published first
    • A user typing npm install nodebb-plugin-example will receive v1.0.0 of the plugin, irrespective of what NodeBB version he/she is running, even though v1.1.0 is technically newer

    Now, special note: The NodeBB Package Manager doesn't do this. When the ACP calls nbbpm to request a suggested package, we query npm for the plugin data, and sort the versions before checking compatibility, so this issue is moot.

Suggested Topics

| | |

Β© 2014 – 2022 NodeBB, Inc. β€” Made in Canada.