Master plan to fix the "plugin"/"module" confusion

[dgw]

Since long before this project was called "Sopel", the .py files one would drop in to add functionality have been referred to as "modules". The code uses it, the docs use it—that term is everywhere. Thing is, Python already has something called "modules", and that makes stuff confusing.

Going forward, we've more-or-less decided to start calling our stuff "plugins" instead. The rewritten machinery to manage them is in sopel.plugins (see #1479). We (those of us who work on the project on a regular basis) are pretty consistent about referring to them as "plugins" on IRC and in new documentation. But there are still a lot of references to "modules" everywhere.

Working on this will probably last the entire life-cycle of Sopel 7. It's not trivial to make such a wide-reaching change in how stuff gets named (or documented), so the implementation plan below is intentionally slow-paced.

Here are the things that [we know] need to be done, sorted by when they need to happen:

• Before 7.0 is released
  • Fix the per-channel configuration stuff (in bot.py) to call them "plugins" (see bot, config: s/module/plugin/ (where appropriate) #1743)
    • There's documentation both here and in the website repo that will need updating to go along with this, as we'll want to rename the new config options etc. before people start using them in a stable release
    • Update relevant docs/guides in website repo (added to Add documentation for per-channel module/command disabling sopel.chat#16)
  • Update the new CLI structure (see cli: replace 'module' by 'plugin' #1742)
    • We currently have sopel configure --modules, for example, which replaces the old sopel --configure-modules option, but the new CLI should call them "plugins"—especially since we also have a new sopel-plugins management tool to match
    • Obviously the old CLI options should still map to their new counterparts; we're in a transition period specifically to avoid yanking those out with no warning
    • The CLI is self-documenting, but the website still needs updating in the migration guide and possibly usage articles (added to Sopel 7 notes sopel.chat#17)
  • Add ~/.sopel/plugins support, working just like ~/.sopel/modules does in 6.x
    • Transitional period, again, because it's always nice to do that if possible
• Through the 7.x life-cycle
  • Audit documentation and code comments for references to "modules" that actually refer to "plugins" and update them (see Audit docs (mostly) for incorrect use of the term "module" #1964)
    • This probably should be split into a list of sub-tasks, but I'll leave that for another time Not necessary; done
  • Initiate rename of sopel.module (all the decorator magic) to sopel.plugin
    • Transitional period might last all the way until 9.0, not sure yet
• For 8.0
  • Remove support for loading plugins from ~/.sopel/modules by default (plugins: don't search in ~/.sopel/modules by default any more #2119)
    • Obviously it can still be added back with the core.extra setting, but renaming the folder is even easier
  • Deprecation warning for sopel.module usage (module: import-time deprecation warning #2170)
    • Ideally just once when the import sopel.module, from sopel import module, or from sopel.module import thing, thing2 statement runs, but if that's unreasonably complicated then we can do the usual instead.
• For 9.0
  • Kill off sopel.module, leaving only sopel.plugin as the place from which to import plugin decorators & constants

As with all our long-term tracking issues, this will get punted from one milestone to the next as tasks for each version target get completed. It's also subject to change based on feedback from collaborators and users, so feel free to comment here or bring it up in our IRC channel!

---

Discarded ideas:

• Possibly stop supporting plugins from PyPI in the sopel_modules.* namespace…?
  • Only a thought, not yet a firm decision
  • NAK. There's no reason to drop it just because the namespace has "modules" in it.

[Exirel]

That's a very good plan. I like it!

[dgw]

Everything for 7.0 is done (or at least in a PR that'll be merged soon). Punting the rest to 7.1, per plan.

[Exirel]

Possibly stop supporting plugins from PyPI in the sopel_modules.* namespace…?

I'm in favor of this. It would mean less code to maintain, and one and only one way to have proper plugins (entry point). Let's add a warning in Sopel 8 and remove that in Sopel 9, that would be fine by me!

[dgw]

Assuming we continue with moving sopel.module to sopel.plugin and drop module in 9.0 as suggested above, removing support for sopel_modules.* plugins at the same time would make sense. Old plugins published in that namespace would probably no longer work with Sopel 9 anyway, because module wouldn't be importable.

Plugins with active maintainers could migrate, in theory. I think nothing prevents one from switching to an entry-point plugin while keeping the original namespaced package name.

Note that we have updates to make elsewhere if we're committed to this plan—the cookiecutter template still has a tagged version people can use to generate new namespace packages, and more importantly the website tutorial still talks about these.

My current mini-project is figuring out if it's possible to keep Sphinx references to sopel.module contents working, at least until we remove the compatibility layer, but so far I haven't had much luck. I might just declare that links to docs aren't guaranteed to keep working across versions. Cool URLs don't change, true, but it doesn't seem like anchor/index aliases are a thing.

[dgw]

Self-assigned as reminder to take care of "Audit documentation and code comments for references to "modules" that actually refer to "plugins" and update them". Once that's done, the rest of this can be moved to the 8.0.0 milestone.

[dgw]

And we're done with the 7.x stuff. Moving to the next milestone.

[dgw]

Put back in 8.0: It's probably prudent to have deprecation warnings on sopel.module stuff before yanking the rug out in 9.0.

[Exirel]

but if that's unreasonably complicated then we can do the usual instead.

No it's just calling the function at the top of the module. An import run the code, def is an instruction like any other, so calling a function is nothing out of the ordinary.

[dgw]

Huh, while I was messing around with doing it myself, you opened a PR. I'll take it.

[Exirel]

Everything from 8.0 has been merged. 🎉