Thinking on it further, I think the tl;dr version of my screed above is that the time-to-first-kickass when it comes to plugin development is too long.

It's kinda known that the plugin API and docs can be improved. We're still growing it out, organically, as we do more and more interesting things. That said, the docs are in-repo, so in addition to feedback we encourage and welcome PRs 😁

Yeah... the plugin world is a weird world, and the docs don't quite do enough to lay out a map of what's going on

It changes often enough I think we're somewhat scared of writing docs only to become stale 😞 However I do think we're starting to conform on an API

@better-boots-10807 your criticism was invited, on-point, and expressed thoughtfully. So I won't agree it's a screed. 😉 Good points raised, thank you. As Josh and Josh note, with the plugin API in flux we've been a bit wary of deeply documenting it yet. But all the more reason why it's valuable to understand the effect on new users. We definitely don't intend for newcomers to struggle to grok the design; we just have been wary of making promises while the plugin API is subject to change. So it's helpful to know that decision has developed unwanted side effects.

Josh and Josh

👬 I'd love for us to get more comfy with docstrings in the codebase though. That won't solve all our issues, but does help the newcomer grok certain aspects. I know I could be better about writing docstrings...

@flat-zoo-31952 @flat-zoo-31952 any thoughts on what to add to the agenda for Sept's Pants Team meetup? Given that API stabilization was a discussion point in August's meetup, I wonder what we can do this month to keep driving momentum forward — whether wrt the API itself or documenting its current logic more thoroughly. /cc @wide-midnight-78598 @hundreds-father-404

There are only 2 people in the world I permit to call me "Joshie" 🙂

That's two more than I imagined.

Am I one? 🤔 😊

Strictly speaking, it's the two women that at some point in my life have made sure I didn't starve to death. My mother and my wife 😂

Stabilizing the plugin API is a big topic. I'd argue that locking it in the way it is now might be counter-productive. And this is from someone who's pretty passionate about stable APIs. I think we be focusing on making it more approachable

There are only 2 people in the world I permit to call me "Joshie"

@bitter-ability-32190 Is one of them me? That is my last name (without the e)

We can start by gathering what threads are ongoing to make it more graspable (docs, in-code docs, explorer, enhancements to

help

) and maybe even just envisioning an ideal developer experience so we know what we're striving for

There's 2 halves to the "Plugin API" as well. The high-level "how does a plugin interact with the core/engine". Then there's an individual aspect of the core/engine's API (e.g. a formatter). The open ticket regarding stability is the former. Meaning we don't feel confident we still fully have down the high-level. I expect when we put a bow on that, there's a longer and harder discussion about a particular Plugin's API stability.

documenting its current logic more thoroughly

I think this is big. There are a lot of docstrings and comments in the mainline repo right now, but I dunno - generally just reading it is never enough for me. I end up looking at as many examples in the codebase as possible, to cobble together some understanding of classes I'd never used before. I did mention this before that it was something like 4 hours of reading and reviewing code to implement a 10 minute feature the "Pants way" I think because in our repo, there are multiple ways to achieve the same end goal, and its common in the plugin world to see all of those ways, rather than "the" way... I've mentioned this before, but I wish there was a way to actually strip back a lot of functionality when making a plugin unless we need "advanced" features. Whether that's part of a plugin API, or somehow hidden behind modules/namespaces/types - dunno edit: API "surface area" is basically what I'm describing

There's also the general fact that the plugin API is like some weird Haskell-Python hybrid with a DAG engine bolted on, and I think it's pretty unintuitive to boot. Most programmers are used to looking for edges (functions, methods, etc), not nodes (data types). It's not wrong it's just very strange.

I think because in our repo, there are multiple ways to achieve the same end goal

Thats a problem in itself and it does irk me at night (or in the morning, whenever my son is awake)

Part of the confusion for me is that Targets feel like they should be nodes but they’re not really, they’re kinda meta-nodes.

Yeah FieldSets are the bridge. The reason (how I understand it) is that this way allows for plugins to define new target types and use existing field sets for ultimate customizability

Yeah, and that makes sense.

Agreed 😔

I think the other thing that might be useful is a spike on a “top-down” API since it sounds like the lower parts of the API are reaching a useful level of stability.