Added backend/plugin contribution note

[sureshjoshi]

Disclosure: I used ChatGPT 5 to write the plugin warning... Which is probably why it's so mid - I just wanted to ensure there was some warning on the page, that we can bike shed upon

In the spirit of contribution notes: #22982

The suggestion here was discussed in the monthly meeting today, where plugins/backends should likely start as in-repo plugins, before being merged into Pants.

Also updated/removed some timings.

[sureshjoshi]

Not finalized language, but I wanted to capture this - since I specifically call out to in-repo plugins.

Maybe if WASI was finalized, we could launch plugins in a WASM sandbox - that would be dope.

[sureshjoshi]

I think this is dated. We already have people pinging when PRs have gone a while anyways, I'd rather not prescribe a specific timing on it.

[cognifloyd]

Dropping the specific time frames is much better for a community driven project like pants, as we don't have the corporate resources to guarantee such a schedule.

[cognifloyd]

Dropping the specific time frames is much better for a community driven project like pants, as we don't have the corporate resources to guarantee such a schedule.

[cognifloyd]

Suggested change

	:::danger Do you trust the authors of the plugin?
	Plugins can run arbitrary code. Review the plugin source or vet the publisher before installing, and consider running it in a restricted environment until you trust it.
	:::
	:::danger Using plugins published by others
	Before you add a plugin, ask yourself: "Do I trust the plugin's authors (and the plugin's publishers)?"
	Plugins can run arbitrary code. Review the plugin source or vet the publisher before installing, and consider running it in a restricted environment until you trust it.
	:::

This title in my suggestion references the last thing mentioned in the doc, which should help this flow better and be less jarring (or "mid").

[sureshjoshi]

Thanks, will take any help - this was just a placeholder to ensure this topic was captured

[cognifloyd]

I typically end up developing pants plugins in my fork of the StackStorm project's codebase. For the most part, I don't submit the plugin in a StackStorm PR because there are not many active contributors, and none of them are comfortable reviewing pants plugin code. So, I try to only submit StackStorm PRs with plugins that cannot be generalized into something that other projects can use.

I don't feel comfortable developing a plug-in under cognifloyd/* and adding it as a dependency of a large open source project like StackStorm because no one else has reviewed the code. So, even if I did the drafting in an external repo, it still would only be used by me (and CI) in my StackStorm fork.

Once I've drafted the functionality I need--and identified the scope of something that could be generally useful--I start working on adding it to pants. For me, preparing a plug-in for general distribution with pants leads to more refined, higher quality, better tested code. That is because I strive to create tests for all the new functionality, flesh out all docstrings so --help output is as useful as possible, and refactor until it looks like something maintainable that can be used--hopefully reliably thanks to the testing--by others.

So, since I'm not drafting this in a codebase that others use (it's only in my fork or a branch), I don't normally follow this admonition to develop it as an in-repo plugin "with real users". I do feel bad that I don't follow this development best-practice. I also can't think of a way to describe my process so that others could use (part of?) it. Thus, I'm not sure if or how I would change any of your wording here.

With this comment, I suppose I'm just trying to make sure what I'm doing is ok, and see if there's a way my approach could possibly help others too.

[sureshjoshi]

Wasn't intentionally an admonition, but more of a point that there are lots of Pants users, but a new plugin might have zero (actual) users - thus there might be a false sense of stability/capability/completion.

The stability part is an important one too, as when there is a bug or requested feature in a new and experimental plugin, the ticket gets issued in Pants - and none of the maintainers/reviewers might have ever used the plugin or have a clue about it. Something as simple as "plugin XYZ doesn't have this incredibly obvious capability" - and all I would be able to say is ... 🤷🏽

StackStorm feels like a bit of an edge case to this policy. And, honestly, this is more of a contribution policy for those who are a bit newer to Pants contributions.

A couple of questions though:

I don't feel comfortable developing a plug-in under cognifloyd/* and adding it as a dependency of a large open source project

Yep, that's totally reasonable - what about a StackStorm/pants-plugins repo? Suffers from the same review burden I guess.

For me, preparing a plug-in for general distribution with pants leads to more refined, higher quality, better tested code

You lost me here. How does the code living within the Pants repo lead to those things? Those all feel like plugin-location ambivalent items? I would have assumed the opposite - as iteration time is so much faster outside of Pants.

However, that's a very individual thing. I always work better with faster iteration times... Though, in all fairness, I have extra tooling outside of Pants to help me out - so I guess that fact is also very individualistic to me 🤷🏽

I do feel bad that I don't follow this development best-practice.
I suppose I'm just trying to make sure what I'm doing is ok,

I mean... It's a candidate suggestion I just came up with it two days ago 😆

[cognifloyd]

I mean... It's a candidate suggestion I just came up with it two days ago 😆

Nah. I've heard it many times over the years, and I be done think you're the only one who has expressed this preference.

[cognifloyd]

For me, preparing a plug-in for general distribution with pants leads to more refined, higher quality, better tested code

You lost me here. How does the code living within the Pants repo lead to those things? Those all feel like plugin-location ambivalent items? I would have assumed the opposite - as iteration time is so much faster outside of Pants.

Open source projects tend to have higher quality standards than proprietary code (in my experience). It has to be maintainable as resources are limited. Iterating within pants vs outside of pants is quite subjective - CI is extremely slow in StackStorm because we're running faster pants-based CI alongside the slower Makefile until the rest of the Makefile functionality is successfully replaced with pants. Thinking about how to structure my plugin so that it lends itself to submitting it in a series of smaller PRs has helped me come up with better abstractions that are easier to review. I carefully write PR descriptions to minimize effort required from code reviewers, and that often reveals shortcomings and code smells that I want to clean up before actually requesting reviews. For in-repo plugins, I often use hackier approaches like throwing deps in a random resolve instead of creating a full subsystem, or using open() because I know the context the plugin is running in so, it's fine. So, in my mind hacks and messy exploratory code belong in-repo and quality, well-tested, clean code goes upstream.

[cognifloyd]

For me, preparing a plug-in for general distribution with pants leads to more refined, higher quality, better tested code

You lost me here. How does the code living within the Pants repo lead to those things? Those all feel like plugin-location ambivalent items? I would have assumed the opposite - as iteration time is so much faster outside of Pants.

Open source projects tend to have higher quality standards than proprietary code. It has to be maintainable as resources are limited. Iterating within pants vs outside of pants is quite subjective - CI is extremely slow in StackStorm because we're running faster pants-based CI alongside the slower Makefile until the rest of the Makefile functionality is successfully replaced with pants. Thinking about how to structure my plugin so that it lends itself to submitting it in a series of smaller PRs has helped me come up with better abstractions that are easier to review. I carefully write PR descriptions to minimize effort required from code reviewers, and that often reveals shortcomings and code smells that I want to clean up before actually requesting reviews. For in-repo plugins, I often use hackier approaches like throwing deps in a random resolve instead of creating a full subsystem, or using open() because I know the context the plugin is running in so, it's fine. So, in my mind hacks and messy exploratory code belong in-repo and quality, well-tested, clean code goes upstream.

[cognifloyd]

Dropping the specific time frames is much better for a community driven project like pants, as we don't have the corporate resources to guarantee such a schedule.

[cognifloyd]

Dropping the specific time frames is much better for a community driven project like pants, as we don't have the corporate resources to guarantee such a schedule.