-
Notifications
You must be signed in to change notification settings - Fork 2.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add explanation/concept for extension maturity model #42446
base: main
Are you sure you want to change the base?
Add explanation/concept for extension maturity model #42446
Conversation
764738f
to
16e3f8e
Compare
Status for workflow
|
This comment has been minimized.
This comment has been minimized.
16e3f8e
to
9c13618
Compare
This comment has been minimized.
This comment has been minimized.
9c13618
to
586b196
Compare
This comment has been minimized.
This comment has been minimized.
586b196
to
426380d
Compare
This comment has been minimized.
This comment has been minimized.
426380d
to
cc470d6
Compare
This comment has been minimized.
This comment has been minimized.
** Use build-time application knowledge to eliminate wasteful runtime code paths | ||
* Codestart application template | ||
|
||
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! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 ?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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"
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?
** Works in JVM mode | ||
** Works in dev mode | ||
** Works in native | ||
* Dev service (if there is an external service dependency) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
shouldn't this not be under developer joy?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.'
* 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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
* 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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
|
||
=== Works in dev mode | ||
|
||
In some cases, extra work may be needed to ensure any wrapped libraries can tolerate |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good point but wouldn't it be better fitting on dev joy?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
i see the graph now have "joy full programming model" is that a missing removal or intentional?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
good stuff! just suggestion on cleaner ordering
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like the general idea.
I added some comments here and there.
* Codestart application template | ||
|
||
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Perfect! (sorry forgot about it!)
|
||
== Dev service | ||
|
||
To provide a dev service, use the `DevServicesResultBuildItem` build item. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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? :)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 … :)
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 |
This comment has been minimized.
This comment has been minimized.
🎊 PR Preview 2c9a5ac has been successfully built and deployed to https://quarkus-pr-main-42446-preview.surge.sh/version/main/guides/
|
This comment has been minimized.
This comment has been minimized.
Is there something I can do on this change to get it unstuck? |
Hi @maxandersen and @gsmet, what's the prognosis for this PR? |
What are the next steps for this work? |
Hi @maxandersen and @gsmet, is there anything I can do to get this moving? |
@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? |
|
||
What makes a good Quarkus extension? What capabilities is a Quarkus extension expected to provide? | ||
|
||
image::extension-maturity-model.svg[A maturity model: Runtime actually works,Works in JVM mode,Works in dev mode, Works in native,Configuration support,Dev service,Dev UI, Use build-time application knowledge to eliminate wasteful runtime code paths (supersonic subatomic performance),Use build-time application knowledge to remove boilerplate,Codestart application template] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
what does the bracketed smiley face indicate?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
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 :) |
@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? |
I don't mind i will review today! |
@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 |
Thanks, @melloware! I have plans (someday) for more automated validation of the |
5fe66a8
to
b8a74ea
Compare
This comment has been minimized.
This comment has been minimized.
Co-authored-by: Guillaume Smet <[email protected]>
Co-authored-by: Guillaume Smet <[email protected]>
Co-authored-by: Guillaume Smet <[email protected]>
b8a74ea
to
37d6c9a
Compare
Hi @gsmet and @maxandersen could you please offer some guidance about the next steps for this PR? |
Status for workflow
|
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.