Soliciting opinions on a plugin CLI

[sureshjoshi]

This is mostly a screenshot-driven discussion based on some ideas I had early in my maintainer ship that I'm finally getting time to get back to.

This originated as an annoyance I had that there was a lot of boilerplate to create a new plugin (the need for new plugins was largely alleviated by adhoc_tool).

So, my idea was to have a slim CLI around the act of creating and cookie-cuttering plugin code. I've picked this back up with the start of a migration tool to help migrate in-repo plugins on breaking changes. Again, early days and just a proof-of-concept right now.

https://github.com/sureshjoshi/pants-plugins/blob/e5c2a2e735621b1cc6fbfe02d8eee9215a431079/pants-plugins/experimental/migrate/rules.py#L18-L49

Below preview means experimental.

I'd be interested in hearing any gripes devs have in building in-repo plugins that might be solved by a simple CLI. This does not cover something like "rule errors are hard", for which we have another solution - and there's nothing much to do here for that problem.

[tdyas]

Regarding migrations for plugins (whether in-repo or out of repo), maybe beneficial if plugins could declare a version of the (still unstable) Pants API they require? And we would have to export an API version from Pants. The thought is that the API need not be stable before we start using semantic versioning. (Thought we could end up with like v151.87.3 etc. etc.)

[sureshjoshi]

My original thought was to couple versioning strictly to the Pants version, until we had an API - lest we then have to break our pre-API contract in the event anything changes post-API contract 😆

e.g. We're generally doing 3-release deprecations, so the idea would be that someone on Pants 2.19 would have to have run the upgrade functionality in order to safely upgrade to Pants 2.20 (then, whenever we do get API stability - for which I anticipate there will be "layers" - we can lock down against API major versions)

[benjyw]

I guess my instinct is to get rid of the need for boilerplate rather than making boilerplate easier to generate... ?

[sureshjoshi]

Fair point, but from that presentation:

~325 lines of boilerplate to support these 11 lines

Where the 11 lines was the meat of the code running just the PyRight process, and the rest was support code for Pants to set that up, subsystems, etc. I can't recall if that included copyright headers (I don't think so).

So, even if we can get that down to 50-100 lines of boilerplate (+ tests), it would still be good to not have a human copy/paste that from somewhere. Also, ensuring the correct boilerplate for a given goal is in place would be a quality of life improvement.

I don't see a world of exactly zero boilerplate, but as we reduce/change it, this plugin CLI would need to adapt as well.

[tdyas]

Regarding boilerplate, I view library-style boilerplate as okay since "control" remains with the plugin's code, and it can adopt whatever paradigm it wants. Framework-style boilerplate, on the other hand, forces a particular paradigm on the plugin code and is "passive" by design.

And our plugin hooks are framework style. Plugins declare rules via the rules plugin hook, but Pants could have discovered all of the rules since they were annotated already with @rule.

Contrast this with a library-style plugin API which would provide a register_rules function to be called by the plugin.