Building my first extension guide

[danielpetisme]

This PR aims to provide a step by step guide about Quarkus extension development as discussed in #1964. I tried to be as pedological as possible by explaining the very basic concepts of Quarkus.

[danielpetisme]

@gsmet @ebramirez This PR is clearly a draft but I would appreciate feedbacks on the format before moving forward.
Should I go this deep in the explanation? Should it all in one guide (concepts and extension dev), is it overlapping a documentation?

Thanks

[aloubyansky]

I think it's pretty good. Not too verbose, imo. The request you linked is basically asking for this kind of info, afaiu. Thanks!

[ebramirez]

So far, so good. It conveys the info in the docs into a simple process easy to follow.

But what I was looking forward is what comes next: What goes where in converting a CDI extension like this into a Quarkus extension.

[gsmet]

Nice work. I added a bunch of comments and suggestions.

[danielpetisme]

Whoaa!! Thanks for this complete review. I'll work on the comments ASAP.
Thanks

[danielpetisme]

Quick update, just to lett you know that I struggle with time at the moment. I'll work on this ASAP.

[gsmet]

@danielpetisme FWIW, if you need some additional motivation, we have a lot of people asking for it and for the Maven mojo to create an extension :).

[FroMage]

@danielpetisme do you think you'll have time to update this PR or would you mind if we took this over?

[danielpetisme]

@FroMage Sorry I missed the notification.
I propose to update with the above comments/review and after we see the remaining work to do.

[danielpetisme]

I have a bit of time so I can progress on the doc but I still have 2 issues:

• As @gsmet commented the commands will fail because the extension already exists. The guide can't be a "copy/paste" tutorial and that's something I'm not comfortable with... I don't have enough context to imagine a "hello-world" extension.
  This point will condition the Quarkus internal APIs to show (BuildItem, Template, Recorder, etc.) For a beginner guide, maybe we don't have to be exhaustive, what are the very basics APIs to use ? BuildItem only?
• When I started this documentation there wasn't a clear strategy regarding extension location (in or out the main Quarkus repo). Back then it was simply not feasible to have an extension hosted outside the main repo, I don't know what's the current status. Depending on the location the dependency configuration is not the same (cf. Building my first extension guide #2406 (comment)).

[danielpetisme]

Folks, after a too long break I hqve continued the writing.
Regarding my previous comment:

• I started a sample-greeting dummy extension. This extension will be removed before merging this PR (to permit to run the whole documentation copy/pasting commands). If you have an idea to persist the dummy extension in Quarkus repo (in a branch or a fork somewhere) and still permit to copy/paste command, I take it.
• I describe the current situation, the extension must be part of the Quarkus repo. Whenever it changes we could update the doc.

So far, I only covered the very basic concepts but I tried to be as pedagogical as possible. IMHO, the current extension dev doc should continues to be exhaustive and considered as the reference guide. The doc I'm writing is, IMHO, opinionated (I don't go into details when I don't feel the need to) thus more accessible to new comers.

I would appreciate an another round of review, 🙏

As you will see in the document there are still sections I want to cover, but IMHO, we could publish a first version as is (even with the TODO mentioned). This would permit to remove me from the critical path and let other people to contribute to the writing (@FroMage asked to take over for instance), plus it's easier to have smaller pieces of doc to review rather than 1K lines).

WDYT?

[danielpetisme]

I thought it was helpful to detail how to debug extensions (I had the issue last week).

[cescoffier]

Closing due to inactivity.

[emmanuelbernard]

Do you think, something is salvageable? Inactivity might not be a problem for a guide. Thoughts?

[cescoffier]

It was on-ice for a long time.
I would love to see updates, but it requires quite some edits to be up to date. If someone wants to take over, it's more than welcome.

[geoand]

A step by step guide I think is really necessary. I've heard complaints from a few people lately :)

[danielpetisme]

I do agree the guide does not cover 100% of the extension development. IMHO, the current version could be considered as a chapter1 of a bigger guide.
Building a complete guide is a huge amount of work so I preferred to split it into pieces (it's better to be done than it is to be perfect). I think this part covers the very basic aspects and respond to the recurring complain of the current Authoring Extension Guide complexity, it could be considered as quick win which could be replaced in a future.

I asked for reviews/comments 2 months ago but the PR has been labeled on-ice (I had the discussion in off with @cescoffier, at the time the extension dev method and tools + the docs was under discussion internally if I'm right) so I froze the contribution. If I can have some guidelines I would be more than happy to update the PR.

[emmanuelbernard]

I don't remember plans for it being discussed internally - I've been hunting down most internal Quarkus project conversations, they are now mostly extinct as we want everything to be discussed in the open.

Let me reopen this one and add it to the extension doc epics.

[gsmet]

I added a bunch of comments.

[gsmet]

I added a bunch of comments.

[aloubyansky]

BTW, direct dependency on quarkus-core-deployment isn't necessary once quarkus-undertow-deployment has been added (it gets pulled in as a transitive dep instead).

[danielpetisme]

Good point but the core deployment comes from the MOJO it could be misleading for newcomers. Either we let it as is even though is redundant or we explain it in the guide.

[aloubyansky]

So the test actually didn't run.

[aloubyansky]

@danielpetisme would you like me to take it over? It's been taking quite awhile. I've got some improvements to create-extension on the way #6748

[danielpetisme]

@aloubyansky I rebuild from scratch the extension, you can find the code at
quarkusio/quarkus-quickstarts#404

I tried to fix the typos between this guide and the code.

Regarding your comment on the extension tests.
I looks like if the class is not suffixed with Test and the methods preffixed with test the test isnt' took in consideration :(
I face the same issue in another Quarkus project, I didn't investigate for now.

Anyway, the test is still faillin because QuarkusUnitTest is not starting a mock application thus can't configure Restassured.
Are you facing the same issue ? Do you have any clue why the app does not start? (I'm using 07a1cf6)

I didn't test yet to include the extension into an app. Do you had other errors?

[aloubyansky]

Thanks for investigating. I haven't done any progress yet. I want to get my create-extension PR in first. I'll be on PTO until Wednesday and will get back to this issue when I'm back.

[danielpetisme]

I rebuillt the quickstart
quarkusio/quarkus-quickstarts#404
I have an open point regarding 999-SNAPSHOT vs 1.2.0.Final but otherwise I can properly run the extension tests and I can use the extension in a application.

@gsmet Would you mind to do your review-sniper thing 😄 please.

[emmanuelbernard]

Hey all, this good content is waiting here for ever. At this stage, I'd favor a no/little review and publish, instead of letting it rot? Thouhts?

[gsmet]

Agreed. It slipped through the cracks. I rebased, squashed everything and renamed the file to be consistent with our new naming scheme.

Will merge as soon as CI is green.

[danielpetisme]

Too bad we can't see each others in real, I would have make a T-Shirt with

It was the oldest open PR on the project 😄

Thank you @gsmet to finish it!

[gsmet]

Well, to my defence, it was still with a WIP title and in a Draft status ;).

[emmanuelbernard]

Considering the project has only been public for 14 months, that's good :D

[danielpetisme]

Thank you all folks, I learned a ton of things writing this documentation! Hope it will help.