Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document dependency/versioning best practices for plugin developers #2604

Open
dgw opened this issue Apr 20, 2024 · 0 comments
Open

Document dependency/versioning best practices for plugin developers #2604

dgw opened this issue Apr 20, 2024 · 0 comments
Milestone

Comments

@dgw
Copy link
Member

dgw commented Apr 20, 2024

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
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.
@dgw dgw added this to the 8.1.0 milestone Apr 20, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant