-
Notifications
You must be signed in to change notification settings - Fork 2.6k
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
quarkus-extension manifests and their formats ? #4539
Comments
As I mentioned before, I propose to deprecate this one and simply use something like Otherwise a possible categorization could be build-time info and the rest with the idea of getting the build more efficient by avoiding parsing non-build related files. |
yes, makes sense for that file but does it make sense to also have |
Aside from the issue of where to store the info, I'd like to open up the question of where it comes from. Given that we pretty much force people to use Maven for building (our extension plugin has to run), it could make sense to generate that descriptor file from Maven properties, like: <project>
...
<properties>
<quarkus.extension.name>RESTEasy - Jackson</quarkus.extension.name>
<quarkus.extension.labels>resteasy-jackson,jaxrs-json,resteasy-json,resteasy,jaxrs,json,jackson</quarkus.extension.labels>
</properties>
...
</project> |
If that is not already there in the plugin then sure. It is already generated by merging pom.xml and whatever file you have. I would still like to have a consistent format that users can decide to use or implement support for in Other build systems. Personally I remove everything I can from pom.xml as possible and keep in relevant artifacts. |
Not sure what file you refer to? I'm saying that if name/labels are the only two infos we need to be in this new extension descriptor, I'd rather not require the users to create a file for it. Especially since they have to repeat the |
I have only slightly related comment to this so bare with :) Today I was looking at MicroProfile (MP) stuff Quarkus is covering and it's not easy to find out all guides and extensions related to MP even-though Quarkus and MP relationship is stressed quite often. https://quarkus.io/guides/ - only few hits with Command/Ctrl+F, an example: OpenTracing doesn't contain MicroProfile keyword. Maybe there could be dedicated MicroProfile section which would aggregate all the guides related to MP https://code.quarkus.io/ - 6 hits when searching |
i'm referring to quarkus-properties.json and there already are a plugin to add the groupid/artifactid - It should also support the other values; if not we for sure should add that. primarily in this issue interested in cleaning up our current list of "manifests" files, there are 4 of them using 3 different formats ;) |
I just noticed that it does not auto-generate the file, I'm a sad panda. I'll comment there, then. |
That's a nice idea. One thing though, now that we may have |
It should be generating the file. At least with groupId and artifactId. We could add support for other properties with basic defaults. |
I meant, as part of the build, by our extension maven plugin. Not manually. |
Cool. Yes indeed it would have to avoid ambiguity, as you say. Should I open a new issue for this, then? |
Sure. |
I have some concern about extension identifier (feature name from the build step, should be the artifact name without the quarkus prefix) and config root (that should be but is not always the same of the identifier).
|
+1 to using a plain properties file format for the generated extension metadata. We don't want to require a JSON parser just to read what are a bunch of properties for an extension. +1 to the content of the file coming from |
As long as our values are simple.
I think it's important to take into account that the number of properties may grow and some of them will be relatively long text content, which may be more convenient to keep outside of the pom. For example actual descriptions. @ia3andy wants to have a few kinds of those. |
I'd question any kind of metadata that can't be expressed in a simple manner Why does it matter how many properties we might have in If we didn't have or didn't want, there to be a Maven plugin that executes during the build for an extension, then I can understand the argument for a file in the source tree |
I'm really not talking about files in source tree here - I'm talking about the 4 files we currently have in every extension. We need to document them IMO for how a plugin is written. How and where you put the info should be up to you - we should make it easy to do from your pom.xml but the pom is not something we can/should rely on during runtime thus how its created is separate from the end result. Also, I seriously hope we will have native gradle support for extensions eventually. And to be clear, my first choice is also to use .properties format for these values. |
If a file is 100% generated and therefore not seen by an extension developer, then I don't care too much even though rationalization of # of files makes sense).
even though .properties is not as great at lists. And it seems the |
I think we should pick only one format and one possible location for this (to avoid confusion), I don't have any thought on the format and location. As you said we discussed @aloubyansky, it should be a format that let define textual fields (like long and possibly formatted descriptions). |
Well, As for Gradle, I'm pretty sure you'll be able to express those properties in it as well. |
It even has |
So really we're missing labels and guide, is all. |
Pom.xml Is not inside the generated artifact. Also do we really want to limit extension writers to maven ? Could we focus on agreeing on what the end result will be ? We can have plenty of intermediate ways to get to that result - Pom.xml, a yaml file, gradle contents etc. |
Actually - if noone really seem to care of the resulting format then .properties is the way to go. No extra dependencies and we have ways to map between XML/yaml/JSON to .properties so we can have it in pom.xml or separate file. Its not pretty but it's simple :) |
Well, first I think that's wrong because As for what type of descriptor gets generated, I don't care if it's generated. It could very well be binary as far as I'm concerned, since it's generated ;) |
That doesn't answer what the other files are for - if anyone knows would be great to know if should stay separate or not. |
I've said this enough times here that I'm starting to think you haven't read me or I can't express myself correctly ;) At this point, users must have a If they want to write it, fine, we'll use it. But we have #4551 open to make it unnecessary, and to have the file auto-generated by our extension maven plugin during building, based on input from the Once more, I haven't checked if we have a gradle extension plugin, but if we do I assume it will be trivial to achieve the same by using the info from the gradle build descriptor instead of This will generate the extension descriptor during build, so we won't need to parse the Clearer? |
I agree with @FroMage, I think having those info in the pom or equivalent is the simplest for the developer since it already contains some of the extension info. Like you would do with npm or some other similar project, the project configuration file contains those info. I am against having many different possibilities to configure it (in the pom or in the properties), it makes things more confusing to user (IMHO). |
As for who uses those files:
|
Now, what do they contain?
BTW, you forgot |
Now, does it matter that different parts of the build generate different descriptors? Not sure. But they do get mostly generated at different build phases (APT, extension maven plugin) and would be impossible to generate at the same time, so it's justified to have them in separate files when producing them. Now, if we absolutely must consolidate them, we could consolidate them in the (generated) extension descriptor (that we're discussing here), by aggregating all those generated files into a single one at some point. Is it useful? Not sure. In general I don't mind what files get generated as long as I never have to edit them myself. |
@i3andy I must be missing something here - why are everyone happy to force users to use pom.xml to write this kind of info ? Sure it's convenient that you can but require it I don't grok it. Shouldn't we have application.properties specified in pom.xml too ? I'm missing something in this reasoning :) |
Both of those do use the bootstrap maven resolver though. |
|
Sorry, I meant "this file is explicitely skipped by DevMojo and RunnerJarPhase", but as you say, lost of stuff depends on the boostrap maven resolver. |
Because we only need two user inputs for that file: labels and guide. All the rest comes from other places. The GAV, the name, description are already present in
|
Thanks for the details @FroMage. I'm also fine with separate files if it makes sense and due to the different phases in play at both build and runtimes it probably.makes sense. Reason why I care about their number and formats is that it's the way I learn how things work. I get annoyed by complex build systems and often to remove any misunderstanding I go look at the generated result to grok how things works. And then seeing multiple files with different formats and naming it's not helping. Also I was starting to write up what makes as extension and it just gets messy. Hence my interest in cleaning it up where I can get clean before 1.0. Alexey said he moved the gav outside the metadata info for performance reasons but not sure that applies if we put it in properties and will want to parse the metadata anyways. Weren't you looking for a place to lookup extension id in your annotation processor too? |
My problem ATM is that I have a set of config root class names and need to find which extensions they belong to, and what those extension names are. Not sure how to solve that, frankly. But yeah, if we do aggregate all the current info into one file, then I should be able to get that. |
You don't have these classes package/loader roots ? Should make it possible to locate manifest from there, right ? |
Well, it depends what phase I look this info up. For config we have two phases:
|
I don't have a strong opinion about the format but there's one thing we
need to support: the ability to define lists - we will need it for the
categories as an extension can be attached to several categories.
…On Tue, Oct 15, 2019 at 11:38 AM Stéphane Épardaud ***@***.***> wrote:
Well, it depends what phase I look this info up. For config we have two
phases:
- during APT, once per extension, but that's during compilation and it
may be in runtime or deployment, so the other descriptor may not be there,
probably the wrong phase then
- during the documentation module building, but it currently doesn't
depend on any extension, so I'd have to add a dependency to the extensions.
But it seems like the right phase.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#4539?email_source=notifications&email_token=AAJYOBP6O4FBEDSICTYUD2TQOWFSZA5CNFSM4JAMWMR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBIDSAY#issuecomment-542128387>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAJYOBMEURSKMFFNAHJMXKLQOWFSZANCNFSM4JAMWMRQ>
.
|
Note that you will need more properties down the line :
- display-in-list
- category
- label
- quality status (beta)
- list-of-guides
- pointer-to-smoke-test (at some point)
Etc
All that can be in a Pom and gradle if it can fit naturally. We would still
need a generated version because no way we read a gradle file to find what
we are looking for.
…On Tue 15 Oct 2019 at 11:23, Stéphane Épardaud ***@***.***> wrote:
why are everyone happy to force users to use pom.xml to write this kind of
info
Because we only need two user inputs for that file: labels and guide. All
the rest comes from other places. The GAV, the name, description are
already present in pom.xml.
application.properties on the other hand is a (sometimes) run-time thing
that can be tweaked to change runtime behaviour.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#4539?email_source=notifications&email_token=AACJNWBUU4KOCELLCQRKDJDQOWDXVA5CNFSM4JAMWMR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBIB75Y#issuecomment-542121975>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AACJNWES26KRLOXZ25PVR3LQOWDXVANCNFSM4JAMWMRQ>
.
|
We also need some kind of manual ordering of the output extension list. I have no idea on how we could make that nicely 😅 |
I need to check if it is authorized to use Markdown in the pom.xml description. I find that the current description we have on most of the extension are not clear enough. This is why I would like the description to really give the user information about what he can expect from the extension and maybe a few hints/examples on how to use it. What I have in mind is:
The goal is to avoid the user having to jump from one place to the other many times. Just to you know, if you are against it, I am ready to fight on this matter 😁 |
@ia3andy If you are looking for markdown to put on a page about the extension then i suggest to take a page from visual code extension playbook. They look up the readme.md from specified github location. Then you can go crazy all you want. I wouldn’t put such things in this metadata file. |
@ia3andy by manual ordering what do you mean ? If you mean what kind of order the extension list in the platform is sorted thenthat Is something to handle when generating the platform. Not affecting the core manifests imo. |
@maxandersen yeah that makes total sense, so maybe we need to add the github location of the extension? |
@gsmet define lists as in something more advanced than a comma separated list of ids/labels ? |
That part is externalized in extensions.json or what will replace it. That
does not change.
But it raises the question @maxandersen of how you set the extension and
category ordering if you split extensions.json into pieces.
…On Tue 15 Oct 2019 at 15:03, Andy Damevin ***@***.***> wrote:
We also need some kind of manual ordering of the output extension list. I
have no idea on how to make that nicely 😅
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#4539?email_source=notifications&email_token=AACJNWHJKJPWMWBCGFEOBXLQOW5SHA5CNFSM4JAMWMR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBIVEVI#issuecomment-542200405>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AACJNWBK2QWD7NLNUGL2TJTQOW5SHANCNFSM4JAMWMRQ>
.
|
Hum read me are really working ?
Does it find older versions by tags? People need to be disciplined and on
GitHub.
Also I tend to put how to build things in readme so that’s another
discipline to have.
…On Tue 15 Oct 2019 at 15:44, Max Rydahl Andersen ***@***.***> wrote:
@ia3andy <https://github.com/ia3andy> If you are looking for markdown to
put on a page about the extension then i suggest to take a page from visual
code extension playbook. They look up the readme.md from specified github
location. Then you can go crazy all you want.
I wouldn’t put such things in this metadata file.
—
You are receiving this because you commented.
Reply to this email directly, view it on GitHub
<#4539?email_source=notifications&email_token=AACJNWDGZYPNPUYKQOYXC53QOXCJ5A5CNFSM4JAMWMR2YY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOEBIZUJA#issuecomment-542218788>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AACJNWDICC3Y77VNZF6AJPDQOXCJ5ANCNFSM4JAMWMRQ>
.
|
things that uses readme from your project:
I would say its usage have been wildly tested :) |
@maxandersen can we close this one? |
I would say no as we didn't clean anything up nor documented these yet so its still an issue that should be looked at. |
In #4423 we are pushing towards a model where instead of a singular manually maintained
extensions.json
in core we'll have each extension contain a manifest file. Then each manifest file will be used as input to a platform definition - of which one part will be the list of extensions.For the manifest the current PR suggests a file per extension jar called
META-INF/quarkus-extension.json
with a content similar to this:question is just if json is the "right" format to have ? Would using .properties or yaml be better ?
In addition I see we have a bunch of other files:
quarkus-config-roots.list
quarkus-extension.properties
:quarkus-javadoc.properties
:Do we need all these to be in ~4 different files with 3 different formats ?
The text was updated successfully, but these errors were encountered: