Document `compatibility` field

[ehmicky]

Background at https://github.com/netlify/docs/issues/1064 and https://github.com/netlify/next-on-netlify-enterprise/issues/16

We should document the new compatibility field in this repository's Markdown documentation.

This field is currently used by our own plugins. Based on discussion about it with @verythorough, we should first wait a bit while we try this new field out before documenting it.

---

Previously it was not possible for plugins to add breaking changes. We have added a new compatibility field in plugins.json to support some specific (not all) types of breaking changes.

That field is optional. When present, it looks like this:

{
  "author": "netlify-labs",
  "description": "Automatically run a Lighthouse audit on your site after every build",
  "name": "Lighthouse",
  "package": "@netlify/plugin-lighthouse",
  "repo": "https://github.com/netlify-labs/netlify-plugin-lighthouse",
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "nodeVersion": "<12.13.0"
    }
  ]
}

In the above example: sites with a Node.js version below 12.13.0 will use @netlify/plugin-lighthouse@1.4.3, while other sites will use @netlify/plugin-lighthouse@2.0.0. This applies to all sites, both new and existing ones, as soon as the PR in netlify/plugins is merged.

In other words, compatibility lists previous versions of a plugin for backward compatibility purpose. When no compatibility versions matches, the top-level version is used instead.

compatibility[*].version is an npm exact version, just like the top-level version.

The currently available condition properties are:

• nodeVersion (see example above), which checks against the site's Node.js version. Any semver ranges can be used.
• siteDependencies, which checks against the dependencies or devDependencies in the site's package.json. Any semver ranges can be used.

{
  ...
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "siteDependencies": { "next": "<=10.0.5" }
    }
  ]
}

When a site is using a plugin's compatibility version, a warning message is printed in the build logs, indicating that a new version of the plugin is available but that specific conditions must be matched in order to use it. For example, this would print something along the lines of "plugin@1.4.3 is outdated: plugin@2.0.0 is the latest version but this is incompatible with next <=10.0.5".

It is also possible to specify a migrationGuide URL which will be printed in that warning message.

{
  ...
  "version": "2.0.0",
  "compatibility": [
    {
      "version": "1.4.3",
      "siteDependencies": { "next": "<=10.0.5" },
      "migrationGuide": "https://github.com/netlify/netlify-plugin-example/MIGRATIONS.md#2.0.0"
    }
  ]
}

[ehmicky]

When we document this field, we should also document the fact that every major version release should keep the old major version as a compatibility field.

This ensures that sites using the old major version due to version pinning are still getting the correct version (including any backports). (see https://github.com/netlify/pod-workflow/issues/17 for more information)

[verythorough]

Adding this to the backlog to go with the other plugin versioning work. When we release version pinning, I imagine it makes sense to document both versioning options together.

@rstavchansky I'm assigning this to you to get it on your radar, but I also recognize that you have multiple other priorities ahead of this work. ❤️

[verythorough]

@rstavchansky and I chatted about this content a while back, and it currently seems to make the most sense to go in this repo, alongside the docs for adding a plugin. I can find three places for updates:

• The main content, describing how to specify versions and compatibility could go under the Update a plugin section of the contributor guide.
• Also in the contributor guide, the line describing the version property could add a note referring to the detailed section about versioning.
• The line in the reviewer guidelines about breaking changes not being allowed should be updated to mention the versioning syntax instead, and link to the new section about versioning.

What do you think, @rstavchansky? One potential alternative could be to put another H3 under the "Add a plugin" section, right after that line describing the version field, instead of putting it in the "Update a plugin" section. Initially, I was thinking the only time multiple versions would be relevant was at update time, but there are scenarios where an author might want two versions available (selectable based on some compatibility value) from the start.

When we have content placement agreed upon, I think this could be a good case for @ehmicky and/or @vbrown608 to make an initial PR and @rstavchansky to review. What do y'all think?

[rstavchansky]

@verythorough Thanks for this audit/plan of what needs updating.
In answer to your question, I think the more common use case will be when updating a plugin, so it would be fine to put the content under the Update a plugin section of the contributor guide. It's not far from the Add a plugin content, so users will likely see it at the same time.
I'm happy to review a PR and make any necessary edits.

[ehmicky]

We just discussed with @vbrown608, and I am happy to submit a PR for this 👍

[ehmicky]

PR at #324.