I wrote a decent chunk of text for the 8.0 migration guide that we all ultimately decided didn't belong there. It was about Sopel's API lifecycle and how plugins should decide which versions of Sopel to support.
That's a better thing to talk about in the Plugins section of Sopel's docs. I think we'll want a dedicated page about this stuff, in the end. Topics to touch on include:
Sopel's deprecation policy
Sopel's Python version support commitment
Making sure your plugin requires the right minimum version of Sopel
A (brief!) discussion of maximum version constraint pros/cons in the context of Sopel specifically
(As usual, y'all feel free to suggest more things and the list can evolve. 😸)
What was removed from the Sopel 8 upgrade guide, for posterity and/or inspiration
```md
This is a good time to remind you that your plugins can specify both minimum and
maximum Sopel versions in their requirements. If all plugins a bot owner wishes
to install contain this metadata, they can ask `pip` to install Sopel and all of
its plugins in a single command, and `pip`'s dependency solver will figure out
which version of Sopel satisfies all of the plugins' needs.
We do everything we can to keep breaking API changes to *only* major versions,
so a version range like `sopel>=7.1,<9` is typically safe—at least the earliest
Sopel version your plugin supports, up to (but excluding) the next unreleased
major version.
In the vast majority of cases, removed API features will first go through a
deprecation period, during which Sopel will log warnings whenever the deprecated
functionality is used by a plugin. Rarely, we might need to remove an API
feature without going through this process—but that's a last-resort option.
```
I wrote a decent chunk of text for the 8.0 migration guide that we all ultimately decided didn't belong there. It was about Sopel's API lifecycle and how plugins should decide which versions of Sopel to support.
That's a better thing to talk about in the Plugins section of Sopel's docs. I think we'll want a dedicated page about this stuff, in the end. Topics to touch on include:
(As usual, y'all feel free to suggest more things and the list can evolve. 😸)
What was removed from the Sopel 8 upgrade guide, for posterity and/or inspiration
```md This is a good time to remind you that your plugins can specify both minimum and maximum Sopel versions in their requirements. If all plugins a bot owner wishes to install contain this metadata, they can ask `pip` to install Sopel and all of its plugins in a single command, and `pip`'s dependency solver will figure out which version of Sopel satisfies all of the plugins' needs. We do everything we can to keep breaking API changes to *only* major versions, so a version range like `sopel>=7.1,<9` is typically safe—at least the earliest Sopel version your plugin supports, up to (but excluding) the next unreleased major version. In the vast majority of cases, removed API features will first go through a deprecation period, during which Sopel will log warnings whenever the deprecated functionality is used by a plugin. Rarely, we might need to remove an API feature without going through this process—but that's a last-resort option. ```