One issue with our documentation on plug-ins is that it is too hard to follow along interactively. There is too much theory you need to know first before you can actually start using things. Two ideas to fix this: 1. Use

RuleRunner

right away. We only mention it in the context of test. But I realize it might be useful when you are developing a rule, because it is basically the way that you can call your rule like you would call a normal function. (The main challenge is getting the rule registration to work) 2. Expose a new plug-in hook specifically for the sake of instruction. Users can hook into this right away, which will activate the goal for them Thoughts?

Oh, this is an interesting and challenging topic.. will give it some thought 🙂

something I felt (and this is definitely my experience and possibly because of what I was trying to do in a plugin) but I felt the plugin examples were a bit too simple and too similar to things pants already does like adding a linter. I was trying to add a new language basically and at a high level I knew it was possible but the docs were a bit less helpful. I ended up reading a lot of the pants src instead. Also the smaller code samples are useful but it would be great to have complete examples that can be ran directly. That is my 2 cents! hope it helps

Totally agreed Kevin! We're planning on re-writing the example plug-in repo to have many more examples

I'm still working on getting v1 of my plugin working for what we need at work but after I get it running there I would like to think about contributing some of it back or at least writing about it (it may be too specific to our use case). I've got pants building Fedora rpms using Buildah 😄

Very cool! Some people might be interested in that similar to https://github.com/pantsbuild/pants/issues/12421 At a minimum, that would be a great blog post

I think that pushing for the use of

RuleRunner

early on is a good thing, where as to have instructional functionality I think would simply add more to the mix of things to learn (and later not use?). Rather it would be better to simplify APIs and onboarding using the regular features. It could be worthwhile exploring the possibility to create “stub” projects within a repo, and/or support creating an entire repo from scratch with a simple command, where you get all the scaffolding in place and can start playing around, hitting the ground running, so to speak. The hard part is starting from a clean slate, so if we can help fill that with content up-front, I think it would help quite a bit. Also, the RuleRunner should be made real easy to use, best case, it would pull in all the rules required for a test from a pool of all available rules rather than you having to know which ones to register. My 2 cents, so far.. 🙂

Thanks! That is a really fascinating idea to ship a goal that is an interactive tutorial