Include the extension status explanation and use status derived from extensions if not defined explicitly#2519
Conversation
…extensions if not defined explicitly
|
🎊 PR Preview 77cc3bd has been successfully built and deployed to https://quarkus-site-pr-2519-preview.surge.sh
|
|
For the guides, I'd say we keep it simple text link. I also again question not having "stable" visible as a status instead of the invisible default. This way people know and it could prevent confusion. |
|
thanks 🙂, having just a link looks good and we wouldn't need to repeat the text in multiple places 👍🏻 I like that too 🙂 As for the label, you think we shouldn't keep the colour ? (my thinking was that it would be nice to show the user the same "coloured label" they noticed on the search results when they open the guide itself ... but if you think it's better without colors here I'm fine with that 🙂) About |
|
@insectengine the idea with the bright colours was to make sure people would never use this extension by accident without knowing their status. So we need something more visual than just a regular link. Perhaps it should be a simple link for "stable", and colours and warning and inline text for anything else? This would achieve the "disclaimer" function we want. |
gsmet
left a comment
gsmet
left a comment
There was a problem hiding this comment.
I'm all for this but I think we need to discuss this part a bit. See inline.
|
|
||
| if status.nil? || status.empty? | ||
| extension_statuses = doc.attr('extensions', '').split(',') | ||
| .map(&:strip) | ||
| .reject(&:empty?) | ||
| .map { |s| s.gsub(/[.:]/, '-') + '-extension-status' } | ||
| .map { |s| doc.attr(s, '') } | ||
| status = ['experimental', 'preview', 'deprecated'].find { |s| extension_statuses.include?(s) } | ||
| end |
There was a problem hiding this comment.
This part is a bit dangerous IMO. IIRC, the extensions metadata can be a bit broad as they are used for search.
I wonder if maybe you should only take into account the first one? But then we would have to check the metadata is correct and that the first one is ALWAYS the right one.
There was a problem hiding this comment.
The "upstream" part of the docs (quarkusio/quarkus#52100) will always include a definitive status based on the list of extensions per guide, by selecting the "least favourable" status.
I'm not sure how we can fall into this branch if that's the case.
There was a problem hiding this comment.
mmm I remember seeing the guide link in the extension metadata yaml:
if we go with that ? meaning if we get the status from that extension's yaml and "assign" it to the guide it mentions, instead of just taking the list of extensions specified in the adoc ( https://github.com/quarkusio/quarkus/blob/39f7eb8c51ff55216bf50626efa46362490e7971/docs/src/main/asciidoc/hibernate-search-standalone-elasticsearch.adoc?plain=1#L12)
so after going through all yamls we'd have a map of <guide, List<extension>> ? would that be a more reliable source ?
(just thinking out loud 🫣 🙂 )
There was a problem hiding this comment.
another idea I had was to say something like:
this guide mentions extensions that are in the following statuses : ...
and show them in a "table format" with status, and list of extensions in that status
There was a problem hiding this comment.
I'm not following the discussion here. What does #52100 do then if not fetch the statuses of all extensions per guide, so it can be used here?
There was a problem hiding this comment.
right, it fetches the statuses of extensions from their yaml files, and then it looks at the :extensions: attribute inside of the adoc file to see which extension statuses to "combine"
and I was asking if "ignoring" the attribute in the guide (:extensions: ) and instead using the guide link in the extension's yaml:
guide: "https://quarkus.io/guides/hibernate-search-standalone-elasticsearch"
would be better...
I've no idea, maybe that's the same info just in two different places, maybe not 🤷🏻 🫣 🙂
There was a problem hiding this comment.
There must be something I don't understand. If quarkusio/quarkus#52100 will correctly set the :extension-status: for every guide, why can't we use it here instead of trying to recompute it?
Agreed. The text can change color for each of the statuses to match the tags in the extensions catalog. |
4 participants
This updated asciidoc extension would inject the status label and explanation next to it, so we wouldn't need to remember to include the
extension-status.adocinclude and make things a bit more "automated"A few previews:
cc: @yrodiere @FroMage @insectengine @rolfedh