Communicating breaking changes to users

Plugin Development
1

Hi all,

This will be smaller than my last post. The idea with these “Open discussion” prefixed threads is to foster discussion about topics I see get brought up cylically in the neovim ecosystem. Hopefully it contains a mix of advice that some people find useful, and a learning opportunity for me.

There are two things I want to discuss today:

  • Communicating breaking changes to users
  • Developing for neovim HEAD/master vs. a release

Breaking changes

Historically (broadly speaking), breaking changes for a given operating system package could be done via mailing lists or patch notes. Often times a distribution’s package maintainer would “handle” dealing with any of these changes such that downstream users were none the wiser.

With (neo)vim plugins, the situation is slightly different. We will revisit the following, but here are some points of divergence:

  • plugins are often not subject to semver (or versioned at all)
  • plugin managers fetch the package directly from the latest git release
  • users often do not “pin” packages
  • there is not a standardized convention for communicating patch notes

Semantic Versioning

I’m going to make the case most plugins should follow semantic versioning.

One issue to make clear, is many neovim plugins are not considered production ready by their authors (one recent exception is hop.nvim). This means that the typical semver conventions are not enforced. Per the specification:

How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.

To whit, I would like to propose the following modified version of semver for most neovim plugins.

Plugins, like neovim core, should bump the minor version for breaking changes and bump the patch version periodically upon release.

What does this mean for plugin authors? Not much. Periodically cut a release from master. If that change has breaking changes, incremental your minor patch version and add it to the release notes. If there are no breaking changes, increment the patch version. Regardless, summarize the commits since the last release. Conventional commits are invaluable for this, as keeping clean commit messages makes these release notes a breeze.

The importance of tagging releases

If you adopt semantic versioning with this convention, it currently does not buy you much. If a user is using a plugin manager like packer.nvim you have the option of either using a specific release version (or specific git revision for that matter) or using the latest revision of the plugin.

There is no option to follow the latest release, or conditionally prompt/warn the user when there is a semver bump in minor version (for 0.x.x versioned plugins) or major version bump (in 1.x.x versioned plugins). This would be preferable to pinning by git revision, as there is no reason to hold patch updates given a project is correctly semver’d.

This functionality could be implemented, but warrants discussion. I believe adding a mode to plugin managers that supports following the latest release, with an option to hold breaking updates and a convention to warn users about breaking updates (including in the case of following the latest revision via the conventional commit standard (more on that later) will be invaluable.

Communicating breaking changes to your users

There are three primary ways to communicate breaking changes to your users.

  • the aforementioned project versioning (and associated release notes)
  • commit message conventions
  • a communication channel with your users (mailing list, dedicated discourse thread, BREAKING CHANGES github issue)

As we’ve discussed project versioning, lets discuss the latter two.

Conventional commits

I would particularly like to highlight the convention on breaking changes in conventional commits.

BREAKING CHANGE: a commit that has a footer BREAKING CHANGE: , or appends a ! after the type/scope, introduces a breaking API change (correlating with MAJOR in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type .

This can be autodetected by certain plugin managers (such as packer.nvim) and shown to your users.

Communication channels with your users

I wish GitHub offered something more like an official “announcements” feature, but we’ve found helpful in core is creating a Following HEAD:breaking changes issue that users can subscribe to, that way they can receive an email notice and important news update. I have seen this trend adopted in other repositories, and I think given the current options/the (often times unfortunate) multi-utility/visibility of the issue tracker, that this is a good interim solution.

Closing Q&A

Q: But what about lspconfig!?!

A: I’m going to cut version 0.1.0 of lspconfig to coincide with the release of 0.6 later this month (unless anyone objects).

Anyways, thanks for listening. Looking forward to hearing the community’s thoughts.

Michael

6 Likes
2

This is brilliant, thank you Michael!

This is the right move; having some enforcement of guidelines to lead to more stable daily systems for users.

Thanks to you and the rest of the neovim team for leading the way in all these amazing developments.

3

Just to be clear, just because I have the commit bit on the neovim/neovim repository doesn’t give me any power to set or enforce guidelines :slight_smile: I’m also not writing this on behalf of the neovim team, just me. I’m just writing this to kick off the conversation/provide a reference I myself can go back to when writing documentation about plugin writing.

4

That’s fair, and I get the shielding for optics for the neovim team. There are a lot of posts on r/neovim related to instability in plugins, etc; so acknowledging that someone that contributes a lot to neovim is looking to shepherd some guidelines through, is a good/positive move, in my mind.