Skip to content

Include the extension status explanation and use status derived from extensions if not defined explicitly #2519

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.

Sign up for GitHub

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

Draft
marko-bekhta wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Include the extension status explanation and use status derived from extensions if not defined explicitly #2519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 18 additions & 8 deletions _plugins/asciidoctor-extension.rb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,23 +163,33 @@
tree_processor do
process do |doc|
status = doc.attr('extension-status')

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
Comment on lines +166 to +174
Copy link
Copy Markdown
Member

@gsmet gsmet Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

@FroMage FroMage Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

@marko-bekhta marko-bekhta Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mmm I remember seeing the guide link in the extension metadata yaml:

https://github.com/quarkusio/quarkus/blob/39f7eb8c51ff55216bf50626efa46362490e7971/extensions/hibernate-search-standalone-elasticsearch/runtime/src/main/resources/META-INF/quarkus-extension.yaml#L13

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 🫣 🙂 )

Copy link
Copy Markdown
Member Author

@marko-bekhta marko-bekhta Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

@FroMage FroMage Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Copy Markdown
Member Author

@marko-bekhta marko-bekhta Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

quarkusio.github.io/_guides/aws-lambda.adoc

Line 11 in 26264d7

:extensions: io.quarkus:quarkus-amazon-lambda

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 🤷🏻 🫣 🙂

Copy link
Copy Markdown
Member

@FroMage FroMage Jan 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?


if status && !status.empty?
tooltip = case status
explanation_inner_html = case status
when 'experimental'
'This extension requests early feedback to mature the idea'
'<p>The extension(s) discussed here request early feedback to mature the idea.</p><p>There is no guarantee of stability nor long term presence in the platform until the solution matures. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a></p>.'
when 'preview'
'This extension\'s backward compatibility and presence in the ecosystem is not guaranteed'
'<p>The backward compatibility and presence in the ecosystem of extension(s) discussed here is not guaranteed.</p><p>Specific improvements might require changing configuration or APIs, and plans to become <em>stable</em> are under way. Feedback is welcome on our <a href="https://groups.google.com/d/forum/quarkus-dev">mailing list</a> or as issues in our <a href="https://github.com/quarkusio/quarkus/issues">GitHub issue tracker</a>.</p>'
when 'stable'
'This extension\'s backward compatibility and presence in the ecosystem are taken very seriously'
'<p>The backward compatibility and presence in the ecosystem of the extension(s) discussed here are taken very seriously.</p>'
when 'deprecated'
'This extension is likely to be replaced or removed in a future version'
'<p>The extension(s) discussed here is likely to be replaced or removed in a future version.</p>'
else
""
end
label_html = %(<a class="status-label status-#{status}" title="#{tooltip}" href="#extension-status-note">#{status}</a>)

label_block = create_pass_block doc, label_html, {}
label_html = %(<div class="extension-status-icon"><span class="status-label status-#{status}">#{status}</span></div>)
explanation_inner_html = %(<div class="extension-status-explanation">#{explanation_inner_html}For a full list of possible statuses, check our <a href="/faq/#what-are-the-extension-statuses">FAQ entry</a>.</div>)
staus_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)
label_block = create_pass_block doc, staus_block_html, {}
doc.blocks.insert(0, label_block)
end
doc
Expand Down
30 changes: 14 additions & 16 deletions _sass/asciidoc.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,10 +149,8 @@ pre.highlight {
line-height: 1em;
text-transform: uppercase;
font-weight: bold;
text-decoration: none;
display: inline-block;
padding: 4px 12px;
margin-bottom: 35px;
border-radius: 50px;
}

Expand All @@ -161,33 +159,33 @@ pre.highlight {
background-color: var(--tag-stable-background-color);
}

a.status-stable:hover, a.status-stable:active, a.status-stable:focus {
color: var(--tag-stable-text-color);
}

.status-preview {
color: var(--tag-preview-text-color);
background-color: var(--tag-preview-background-color);
}

a.status-preview:hover, a.status-preview:active, a.status-preview:focus {
color: var(--tag-preview-text-color);
}

.status-deprecated {
color: var(--tag-deprecated-text-color);
background-color: var(--tag-deprecated-background-color);
}

a.status-deprecated:hover, a.status-deprecated:active, a.status-deprecated:focus {
color: var(--tag-deprecated-text-color);
}

.status-experimental {
color: var(--tag-experimental-text-color);
background-color: var(--tag-experimental-background-color);
}

a.status-experimental:hover, a.status-experimental:active, a.status-experimental:focus {
color: var(--tag-experimental-text-color);
.extension-status {
display: flex;
align-items: center;
padding-bottom: 1.25em;
}

.extension-status-explanation {
border-left: 1px solid #aaa;
padding: 1.25em;
opacity: 0.8;
}

.extension-status-icon {
padding: 1.25em;
}
Loading