Quarkus: Improving the extensions guides introduction

[loicmathieu]

Description

The extensions guides generally follow this schema:

• Prerequisite
• Architecture (not always present)
• Solution
• Creating the maven project
• ... specific guide sections ...
• Going further

Reading the guides there is sometimes missing sections, and the "Creating the maven project" section doesn't always mention how to integrate the extension in a new project or an existing one.

Sometimes the link to the quickstart is missing.

As a reference, the Solution and Creating the Maven Project sections should be something like the ones of the Kafka guide: https://quarkus.io/guides/kafka

Implementation ideas
To avoid duplicating these sections over and over, we can use asciidoc include to have a unique solution and creating-maven-project section used accross all extensions guides.

The include shoud use variable comming from the main asciidoc file to configure the name of the quickstart and the name of the extensions.
Each extension guide should be updated to use these includes.

[lucas-dclrcq]

I'd like to work on this one if that's ok.

[loicmathieu]

I assigned it to you.
But please, wai for one day before sarting on this one as it's a huge redesign of the guides (extracting parts to an asciidoc include) and I want to give time to people on the mailing list before.
So better to wait one or two days for feedback instead of working on something that will not be accepted.

[loicmathieu]

@lucas-dclrcq I talk with some other Quarkus maintainer and we fear that the PR can be huge and that it may be difficult to extracting the "creating-maven-project" section as it may be customized in a lot of different ways for each extension.

What I propose it to create a first PR that adds the missing solution sections on the guides that misses it. The best way to do this is open the quickstart repo (https://github.com/quarkusio/quarkus-quickstarts) and check that all quickstarts are mentionned inside the guide. And that adds or updates the "creating-maven-project". If you think it's too many work you can provides two PRs to facilitate the review (or at least two commits).

Then, when this first PR will be merged, we can decide if we want to extract the solution section as it should be the same on all guides. This would be a new PR.

WDYT ?

[lucas-dclrcq]

The maven section has often custom steps, but the solution section is pretty much the same everywhere, do I still need to provide an include for this part ?

Can we maybe add a test that ensures the maven section is present for guides ?

[loicmathieu]

Even the solution section is different the guides, I oversee when creating the issue but it often contains a sentence explaining what's inside the quickstart and sometimes link to multiple quickstarts.

Si it's better first to update the guides and see if a pattern really emerges.

Can we maybe add a test that ensures the maven section is present for guides ?

It may be a good idea, I wonder what others think about this one and how it will works. @gsmet @machi1990 WDYT about this idea to have tests on our guides to check the presence of some mandatory section? Note that some guides are "summary pages" so have not quickstart attached to them nor provides any guidance of how to create a Maven project so we may need to exclude them from this test and it will complicate things (an example of this is the security guide: https://quarkus.io/guides/security

[SaumyaSingh1]

Hey @loicmathieu , so the test has been added that ensures maven section is present for guides (extensions introduction)?

[SaumyaSingh1]

Hey @loicmathieu , so the test has been added that ensures maven section is present for guides (extensions introduction)?

If not then I would like to work on improving the extensions guides introduction .

[SaumyaSingh1]

@loicmathieu I realized some of the extension guide are not at all following above schema you mentioned.

[loicmathieu]

@SaumyaSingh1 no test has been added and nothing has been done for this issue.

The situation is a little more complex as not all guides follow the same semantic, and not all extensions have quickstarts. And sometimes one guide has multiple quickstarts and some other didn't have one for a good reason.

You pointed out some guides that have not the good schema, you can update them if you want, this would close this issue for now.

The most important thing to do is to be add the quickstart section if missing.

[SaumyaSingh1]

@loicmathieu I completely agree that not all guides follow same semantic.

As of now I am going to manually prepare a list of the quickstarts that are missing in the guide.

Like amqp Quickstart is not in the guide ( though " _AMQP with Reactive messaging_" topic is present there)🤔

[SaumyaSingh1]

@loicmathieu once done with manual checking, then will start adding the missing quick-start in the guide 🎉

[SaumyaSingh1]

@loicmathieu so as per my inspection🔎 following quick-start are misssing in the guide.

1. Quarkus AMQP 1.0 Quickstart- https://github.com/quarkusio/quarkus-quickstarts/tree/master/amqp-quickstart

2. MQTT Quickstart- https://github.com/quarkusio/quarkus-quickstarts/tree/master/mqtt-quickstart

3. Supporting Multi-Tenancy in Hibernate ORM - https://github.com/quarkusio/quarkus-quickstarts/tree/master/hibernate-orm-quickstart-multi-tenancy

4. Hibernate Reactive and RESTEasy - https://github.com/quarkusio/quarkus-quickstarts/tree/master/hibernate-reactive-quickstart

5. Keycloak Authorization Services and Policy Enforcer to Protect JAX-RS Applications- https://github.com/quarkusio/quarkus-quickstarts/tree/master/security-keycloak-authorization-quickstart

6. gRPC guide is there but separately gRPC TLS is not there.

It would be good if this list will be verified by someone from team.

[loicmathieu]

The MQTT guide is not linked in the website, I don't know the status of the exception, maybe @gsmet knows.

For gRPC, I don't thinks a specific guide should be added for TLS.

For the other, you can add them, it'll be a valuable addition ;)

[SaumyaSingh1]

@loicmathieu
Just a double check I am lill confused
As per my understanding :

1. I have to add the the quick-starts guide that are missing on the website (https://quarkus.io/guides/) e.g MQTT is not on website so I have to add it's detail there on website 🤔 ( _possibly i am wrong here_)?

2. OR some guide on website have the Quickstart link attached like in kafka guide it is attached but in few of the guides it's not attached. So I am supposed to add the link of quickstart there on website like in this picture for kafka ?
   Kafka Guide Screenshot from website

3. OR I just have to add the link of the quickstart-guide _(from website)_ in the Readme of particular quickstart in this repo?
   Like in this picture

I got confused 😶

[loicmathieu]

Sorry for the confusion ;)

You have to add the missing quickstarts inside the guides on the Quarksu repository: https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc

The guides on the website are generated from the guides on each release, you have nothing to do on the website side.
For the MQTT guide missing on the website, you cannot do anything about it.

The README are not used, don't need to update them.

[SaumyaSingh1]

Oh alright, it's much clear now.

I spared last 2 days in building the complete project on my system 😂

Now, I am going to start working on this 👍🏻

[SaumyaSingh1]

@loicmathieu
But little description of MQTT is present here .

What if I add this much detail on Quarksu repository?
Then the details of MQTT will be visible on the website 🤔 Isn't it ?

[loicmathieu]

What if I add this much detail on Quarksu repository?
Then the details of MQTT will be visible on the website 🤔 Isn't it ?

No, there is a step to adds a guide inside the website, and if there is none for MQTT, I assume there is a good reason.

[SaumyaSingh1]

ok so I have to add the missing quickstarts ( _missing on website & present here_ ) in the Quarksu Repository Ascii 🤔🤞🏻
Right ? @loicmathieu

[loicmathieu]

Yes, exactly.

[SaumyaSingh1]

@loicmathieu
The 1st missing quickstart which I want to add in the Quarksu Repository Ascii is this one -
Supporting Multi-Tenancy in Hibernate ORM.

For the content, do I only need to use the README of particular quickstart or should I gather content of particular quickstart from Internet ?

[loicmathieu]

@SaumyaSingh1 for Hibernate ORM multi-tenancy, there isn't a dedicated guide but it's a section of the Hibernate ORM guide, https://quarkus.io/guides/hibernate-orm#multitenancy. Better just add a small section under this one to link to the quickstart.

If you have question, you can contact me on the Quarkus Zulip chat: https://quarkusio.zulipchat.com/