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

[julian]

Hey all,

Re: The breaking changes outlined here:

• 0.6.0 Breaking Changes
• filter:uploadImage and filter:uploadFile changes
• filter:post.parse and filter:post.parseSignature changes
• https://community.nodebb.org/topic/3153/action-topic-save-action-topic-restore-action-topic-edit-changes
• ... and I'm sure there will be more

---

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!

Rationale

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: https://packages.nodebb.org/api/v1/suggest?package=nodebb-plugin-sso-github&version=0.5.3

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

[julian]

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

[a_5mith]

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.

[julian]

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.

[a_5mith]

@julian said:

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

propensity
prəˈpɛnsɪti/
noun

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

verbosity
vəˈbɒsɪti/
noun

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

Yes.

[julian]

Hey guys,

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

[Schamper]

Now I need to update all those plugins of mine

I'll be done somewhere around Christmas with my current free time

[a_5mith]

@Schamper When you've done yours, I'm accepting PRs for mine.

[psychobunny]

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

[a_5mith]

@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.

[julian]

Probably XD. Let me move it there now.

[psychobunny]

@julian said:

I do have a propensity for verbosity

you just summed it all up yourself

[tedr56]

I understand the new concept but why unpublish first?

[julian]

Upon reflection, the unpublishing step is unnecessary

[tedr56]

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

[tedr56]

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

[julian]

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.