Add explanation/concept for extension maturity model

[holly-cummins]

This is part of the bigger plan for extension documentation: https://github.com/quarkusio/quarkus/issues/37288


Obviously, there’s a gap for dev services documentation, which I’ll move on to next. Once I've got something linkable for dev services documentation, I will come back and link here.

One of the links needs quarkiverse/quarkiverse#229 to merge for it to resolve. I decided to be optimistic about the order things would happen and put the link in anyway.

The preview comments aren't working, but this is the link to the new page: https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/extension-maturity-model

Question for reviewers: Should the list at the top be numbered? Or perhaps a graphic, so that it's more distinct from the table of contents lower down? https://en.m.wikipedia.org/wiki/File:Characteristics_of_Capability_Maturity_Model.svg is a somewhat standardised visualisation of maturity models, but it's harder to edit than raw text.

[quarkus-bot]

Status for workflow Quarkus CI

This is the status report for running Quarkus CI on commit 16e3f8e.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.

Warning

There are other workflow runs running, you probably need to wait for their status before merging.

You can consult the Develocity build scans.

[maxandersen]

the list is good - but afaics the only thing that "fits" a maturity model (as in something that is progressively more) is "works in jvm" and "works in native" (too). The rest a checkbox features.

i.e. does it help to call it a extension maturity model or does it confuse more ?

[holly-cummins]

I wondered the same thing, because you're right that the progression is not a strict one. But I think it does make sense to talk about the maturity of an extension. In this context it's a synonym for completeness, but completeness wouldn't be helpful term to use, because it makes it sound like people aren't 'allowed' to do extensions unless they do everything. And 'checklist' has a similar problem - it doesn't have enough progression.

Another way of thinking about it is that it's a model to distinguish a really good extension from an average one, but I don't think any words like 'quality' would be helpful, because there's too much judgement. This should be an aspiration list, not a shame list.

[maxandersen]

yeah, I don't have too strong opinion ....just that in past we kept getting stuck trying to "rank" it .

Alternative suggestion to maturity model I can think of is Capability Model: Emphasizes the capabilities or features that are completed or available.

another is "Implementation Levels: Describes the levels at which different parts of the project have been implemented." but that also "ranks"

[holly-cummins]

The good thing about "maturity model" is that it will be really obvious to people what it means. "This page tells me what my extension will be like when it starts, and where it could eventually end up if I continue working on it." "Capability model" or "Implementation levels" would need some words around it to try to explain to people what the purpose of the page is, because they're not familiar concepts in the same way.

The bad thing about maturity model is that this isn't a maturity model in the strictest sense, because the progression/dependencies on lower levels isn't strict enough. And there definitely could be some debates about the relative position of a few things.

We could change the page title to something generic like extension-capability-model but leave the in-page title as "maturity model". That way if we decide to change the the title later on we don't have a problem with the url?

[maxandersen]

shouldn't this not be under developer joy?

[holly-cummins]

I wanted to pull it out to the top level, because it's so important.

For consistency I could also pull config out to the top level, and leave developer joy to be the more amorphous 'take advantage of quarkus magic to revolutionise your programming model.'

[maxandersen]

Suggested change

	* It actually works
	** Works in JVM mode
	** Works in dev mode
	** Works in native
	* Dev service (if there is an external service dependency)
	* Developer joy
	** Configuration support
	** Use build-time application knowledge to remove boilerplate
	* Dev UI
	* Supersonic subatomic performance
	** Use build-time application knowledge to eliminate wasteful runtime code paths
	* Codestart application template
	* Runtime actually works
	** Works in JVM mode
	** Works in native
	* Supersonic subatomic performance
	** Use build-time application knowledge to eliminate wasteful runtime code paths
	* Developer Joy
	** Configuration support
	** works with hotreload/devmode
	** Dev service (if there is an external service dependency)
	** Use build-time application knowledge to remove boilerplate
	** Dev UI
	** Codestart application template

Totally optional suggestion on grouping it a little bit different as the existing one (at least to me) felt as its categories overlapped a bit too much.

[holly-cummins]

I think if we group too much under developer joy it starts to break the ranking. I'd say that tolerating dev mode is table stakes for an extension, but 'redefine the programming model' is a pretty advanced feature.

What about pulling developer joy some sort of tag or 'key'. So Config and Boilerplate reduction become top level items, dev mode goes back to being in front of native mode, and we put the joy icon at the beginning or end of those lines. Or if we do boxes, the joy icon tags the box.

Then we could do a similar tagging for the others, with some sort of 'speed' icon (I don't think we actually have one, but we should?). So then people can glance at the list and see how each thing fits in. Something like this, but not looking terrible:

Also, in my crappy mock-up I didn't bother to adjust the order of items, and I had to steal an icon since we don't have a speed one.

[holly-cummins]

Or something like this, if we went for a more graphical maturity model representation:

(Again, wrong icon for performance, and I only filled out the first bit.)

[holly-cummins]

I've changed 'it' to 'runtime', as per your suggestion. I've (hopefully) fixed the problem with Developer Joy you pointed out by just removing all of the 'developer joy' nesting. I've not done anything yet with icons or moving to a graphical format.

[maxandersen]

good point but wouldn't it be better fitting on dev joy?

[holly-cummins]

See the comment above - I think if we're suggesting an implementation order, we can't group too much. So let's get rid of 'Developer Joy' altogether from that list, so there's no question of things being sub-points under it or not.

Developer Joy should be a theme, not an implementation order.

[maxandersen]

i see the graph now have "joy full programming model" is that a missing removal or intentional?

[holly-cummins]

The graphic has "joyful programming model", which is intentional. "Developer Joy" includes a whole bunch of things, which would be implemented at different times - so what the graphic is talking about is specifically the boilerplate reduction, and not things like support for live reload or unified configuration.

[holly-cummins]

i see the graph now have "joy full programming model" is that a missing removal or intentional?

Just to add a bit of context, the graphic switched to its current, non-nested, form on August 12th (#42446 (comment)). That was just the visual version of this change in the list, from August 10th:
#42446 (comment)

I wanted to pull it out to the top level, because it's so important.

For consistency I could also pull config out to the top level, and leave developer joy to be the more amorphous 'take advantage of quarkus magic to revolutionise your programming model.'

... and also this comment, also August 10th:

I think if we group too much under developer joy it starts to break the ranking. I'd say that tolerating dev mode is table stakes for an extension, but 'redefine the programming model' is a pretty advanced feature.

What about pulling developer joy some sort of tag or 'key'. So Config and Boilerplate reduction become top level items, dev mode goes back to being in front of native mode, and we put the joy icon at the beginning or end of those lines. Or if we do boxes, the joy icon tags the box.

[maxandersen]

good stuff! just suggestion on cleaner ordering

[gsmet]

I like the general idea.

I added some comments here and there.

[gsmet]

I think it needs to be clear that you don't need to implement all of this before releasing your extension. It's more or less mentioned but people have a tendency to go over the top sometimes when developing in the open and we need to clarify it's OK to publish a first version that doesn't handle everything.

[holly-cummins]

Yes, agree 100%. I was trying to convey that (and I think it's kind of implied by the maturity model), but I will be more explicit about that.

[holly-cummins]

The order in this model isn't exact. Different developers will have different views on what capabilities are most important. You may wish to (say) prioritise performance over enhancing your extension's Dev UI tile. That's fine!
Also, not every step will apply to every extension. For example, you don't need a dev service if your extension doesn't depend on external services.
It's completely OK to publish a first version of an extension that doesn't handle everything. In fact, it's ok if your extension never gets to the more advanced features. This is a suggested pathway, not a minimum feature set.

?

[gsmet]

Perfect! (sorry forgot about it!)

[gsmet]

I think we should try to add pointers to extensions that are good inspiration. Does it make sense?

If so, I suppose your next question will be for me to point them to you? :)

[holly-cummins]

Yes, and no. And yes, but no. But yes. :) For dev services in particular, I’m planning to get out a basic dev service documentation this week, and then cross-link to it from here. So ‘do it this this week’ can sometimes be a fiction, so there’s no harm having links to examples in the interim, but we also don’t need to spend too much time on stuff that I’m hoping to remove in a day or two. Those links to good examples would be helpful to include in the dev services doc, though. 
More generally, I really like the idea of providing pointers to example extensions. I’ve got another doc in draft that’s an an extension FAQ with questions like “I need to remove a method” and so on, and there I 100% want to link to examples to follow. So if you have any … :)

[holly-cummins]

I’ve changed the list to a graphic. This has the benefit of adding something beyond what’s in the ToC below and the base writing-extensions guide. It has the disadvantage it’s hard to maintain. I don’t have the tools to do it, but @insectengine might be able to convert it to an svg, which would still render nicely, but would have a slightly higher bus number than my png.

[github-actions]

🎊 PR Preview 7f5dc76 has been successfully built and deployed to https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/

• Images of blog posts older than 3 months are not available.
• Newsletters older than 3 months are not available.

[insectengine]

Created a slightly different view of the graphic (PNG and .SVG)

[holly-cummins]

Created a slightly different view of the graphic (PNG and .SVG)

Thanks! Visually, that looks way better than mine, but I'm not sure about the shape. I think people's expectations of a maturity model would be a bit more stair-case-y. There's some variation in what google shows, including one pyramid, but almost all of them have a linear progression from bottom to top and left to right:

I had in mind something like this:

Because we have more stages than that example it does make it harder to fit everything on the page, but I think it does make it easier to understand the intent.

[holly-cummins]

@insectengine, I've just noticed that CodeStart is camel-cased in the diagram, but it should be Codestart. I've fixed it in the svg (the joy of svgs), but you might want to update your local copy.

[holly-cummins]

Is there something I can do on this change to get it unstuck?

[holly-cummins]

Hi @maxandersen and @gsmet, what's the prognosis for this PR?

[holly-cummins]

What are the next steps for this work?

[holly-cummins]

Hi @maxandersen and @gsmet, is there anything I can do to get this moving?

[holly-cummins]

@maxandersen and @gsmet, I'd like to be able to refer people to this material. Can you please advise if my best option is take this content and host it elsewhere?

[maxandersen]

what does the bracketed smiley face indicate?

[holly-cummins]

Developer joy. So the idea is that there are several different things extension owners should do in the theme of "developer joy". Now that we have one, we could also take the "performance" icon from quarkusio/quarkusio.github.io#2122 and put that on the performance-related items.

[maxandersen]

@maxandersen and @gsmet, I'd like to be able to refer people to this material. Can you please advise if my best option is take this content and host it elsewhere?

sorry - missed it during travel/sick.

Ineed to refresh my memory - i'll make sure to have re-read it by time we meet at devoxx next week :)

[holly-cummins]

@melloware, I liked your reference to "quarkusifying projects" the other day. It made me realise there's some overlap with what this work item is trying to describe. As our most prolific creator and maturer of new projects, do you mind casting your eye over this? The preview link is https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/extension-maturity-model?

[melloware]

I don't mind i will review today!

[melloware]

@holly-cummins looks great. The only feedback i have when I have been Quarkiversifying extensions and helping others fix theirs is there doesn't seem anywhere there is enough emphasis on making sure the quarkus-extension.yml has the right information, category, icon URL, config, etc. I always look at that first when updating or fixing an extension. Other than that this is great!

[holly-cummins]

Thanks, @melloware! I have plans (someday) for more automated validation of the quarkus-extension.yaml, but that would only partially cover the things people do now. I've added an extra line into the introduction pointing people to that file and explaining that it's important.

[quarkus-bot]

Status for workflow Quarkus Documentation CI

This is the status report for running Quarkus Documentation CI on commit b8a74ea.

✅ The latest workflow run for the pull request has completed successfully.

It should be safe to merge provided you have a look at the other checks in the summary.