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

@gsmet gsmet Jan 20, 2026

Copy link
Copy Markdown
Member

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.

@FroMage FroMage Jan 20, 2026

Copy link
Copy Markdown
Member

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.

@marko-bekhta marko-bekhta Jan 20, 2026

Copy link
Copy Markdown
Member Author

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

@marko-bekhta marko-bekhta Jan 20, 2026

Copy link
Copy Markdown
Member Author

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

@FroMage FroMage Jan 21, 2026

Copy link
Copy Markdown
Member

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?

@marko-bekhta marko-bekhta Jan 21, 2026

Copy link
Copy Markdown
Member Author

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

@FroMage FroMage Jan 21, 2026

Copy link
Copy Markdown
Member

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>'
Comment on lines +179 to +185

@rolfedh rolfedh Jul 18, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Wording suggestion — text-level feedback, so it should carry over to whichever implementation lands after the Roq migration:

  • Align the explanation text with extension-status.adoc (the text readers already see on guides today), with one uniform lead-in pattern: "For X extensions, …". This avoids the "extension(s)" construction, which style guides recommend against, and it stays accurate whether a page discusses one extension or several.
  • The include's lead-in says "In experimental mode", but these are statuses (that's what the FAQ calls them), and "mode" already means something else in Quarkus (dev mode, native mode).
  • Light copy edits along the way: "no guarantee of stability or long-term presence" (after a negative like "no", plain "or" is standard, and "long-term" takes a hyphen before a noun); "are not guaranteed" ("backward compatibility and presence" is two things — the stable text already uses "are"); "plans are under way for them to become stable" (it is the extensions that become stable, not the plans); and the experimental period moves inside </p> — right now it renders below the paragraph, stuck to the FAQ sentence.

The FAQ entry keeps the older wording for now; I can send a small follow-up to align it.

Suggested change
'<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>'
'<p>For <em>experimental</em> extensions, early feedback is requested to mature the idea.</p><p>There is no guarantee of stability or 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'
'<p>For <em>preview</em> extensions, backward compatibility and presence in the ecosystem are not guaranteed.</p><p>Specific improvements might require changing configuration or APIs, and plans are under way for them to become <em>stable</em>. 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'
'<p>For <em>stable</em> extensions, backward compatibility and presence in the ecosystem are taken very seriously.</p>'
when 'deprecated'
'<p><em>Deprecated</em> extensions are likely to be replaced or removed in a future version of Quarkus.</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, {}
Comment on lines +191 to +192

@rolfedh rolfedh Jul 18, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Tiny typo: staus → status.

Suggested change
staus_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)
label_block = create_pass_block doc, staus_block_html, {}
status_block_html = %(<div class="extension-status">#{label_html}#{explanation_inner_html}</div>)
label_block = create_pass_block doc, status_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