Repository navigation
DOCS-3057: Add a component for feature lifecycle notices - #3052
Merged
Merged
Conversation
✅ Deploy Preview for calico-docs-preview-next ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
✅ Deploy Preview succeeded!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
The drift check omits several actively built versioned documentation trees.
Review effort: Balanced
Findings: 1
What changed in this PR
Adds reusable, validated feature lifecycle notices and includes cleanup from stacked PR #3051.
Changes:
- Adds the
LifecycleNoticecomponent and automatic front-matter insertion plugin. - Adds lifecycle-status drift validation and tests.
- Converts two pilot notices and removes obsolete tech-preview notices.
| File | Description |
|---|---|
src/theme/MDXComponents.js |
Registers the lifecycle component globally. |
src/remark/lifecycleNoticePlugin.js |
Inserts notices from front matter. |
src/remark/__test__/lifecycleNoticePlugin.test.js |
Tests notice insertion and validation. |
src/components/LifecycleNotice/index.tsx |
Implements lifecycle notice variants. |
src/components/LifecycleNotice/__test__/index.test.tsx |
Tests component rendering. |
src/components/LifecycleNotice/__test__/drift.test.ts |
Checks notices against feature-status data. |
src/components/FeatureStatusTable/featureStatus.ts |
Exposes status resolution for drift checks. |
docusaurus.config.js |
Enables the remark plugin. |
calico/reference/resources/felixconfig.mdx |
Removes an obsolete preview notice. |
calico/reference/felix/configuration.mdx |
Removes an obsolete preview label. |
calico/getting-started/kubernetes/self-managed-onprem/onpremises.mdx |
Removes obsolete CRD preview notices. |
calico-enterprise/threat/gateway-waf/overview.mdx |
Uses front-matter lifecycle metadata. |
calico-enterprise/reference/resources/felixconfig.mdx |
Uses an inline lifecycle notice. |
calico_versioned_docs/version-3.33/getting-started/kubernetes/self-managed-onprem/onpremises.mdx |
Removes obsolete versioned notices. |
.github/copilot-instructions.md |
Documents lifecycle-notice usage. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+33
to
+45
| const TREES: { dir: string; product: string; version: string | null }[] = [ | ||
| { dir: 'calico', product: 'calico', version: null }, | ||
| { dir: 'calico_versioned_docs/version-3.33', product: 'calico', version: '3.33' }, | ||
| { dir: 'calico-enterprise', product: 'calico-enterprise', version: null }, | ||
| { dir: 'calico-enterprise_versioned_docs/version-3.24-2', product: 'calico-enterprise', version: '3.24' }, | ||
| { dir: 'calico-enterprise_versioned_docs/version-3.23-2', product: 'calico-enterprise', version: '3.23' }, | ||
| { dir: 'calico-cloud', product: 'calico-cloud', version: null }, | ||
| { | ||
| dir: 'calico-cloud_versioned_docs/version-23-2', | ||
| product: 'calico-cloud', | ||
| version: ceVersionFromCloudversion('v3.23.1-4'), | ||
| }, | ||
| ]; |
Collaborator
Author
There was a problem hiding this comment.
Fixed in d5db7e1. The checked trees now come from each product's versions file, so every versioned tree is covered, and a new cut needs no edit to the test.
ctauchen
force-pushed
the
DOCS-3057-mechanism
branch
from
October 8, 2026 14:27
f11292f to
640a6c6
Compare
Contributor
There was a problem hiding this comment.
🔵 Needs a closer look
The drift check excludes four documentation versions currently built and published.
🧠 Review effort: Balanced
Give feedback about Copilot approvals in this survey to enter a drawing for a $150 gift card.
ctauchen
force-pushed
the
DOCS-3057-mechanism
branch
from
October 9, 2026 15:51
640a6c6 to
3425803
Compare
Comment on lines
+105
to
+108
| const ALLOWED: Record<Declarable, CellStatus[]> = { | ||
| 'tech-preview': ['tech-preview'], | ||
| deprecated: ['deprecated', 'removed'], | ||
| }; |
Collaborator
Author
There was a problem hiding this comment.
Agreed, fixed in 75a9212. A deprecation notice no longer accepts a feature recorded as removed.
Comment on lines
+166
to
+169
| it('has something to check', () => { | ||
| // A rename or a moved tree would otherwise make this suite pass by checking nothing. | ||
| expect(TREES.filter((tree) => mdxFiles(tree.dir).length > 0)).toHaveLength(TREES.length); | ||
| }); |
Collaborator
Author
There was a problem hiding this comment.
Fixed in 75a9212. The suite now fails when it finds no declarations.
Technology preview and deprecation notices were hand-typed prose repeated across 133 pages in at least eight wordings, which is why notices outlive the status they describe. This adds one way to write them. A page that is wholly about a feature declares the status in front matter: lifecycle-status: tech-preview lifecycle-feature: Gateway WAF lifecycle-id: gateway-waf A new remark plugin places the notice directly after the page title, where every hand-written notice already sat. It inserts the component rather than building an admonition, so the front matter form and the hand-placed form render through the same code and cannot drift apart. When only part of an otherwise generally available page is affected, or the notice needs extra guidance such as what to migrate to, the component is used directly in the page instead. The feature name is the admonition title rather than the subject of a sentence, so that one fixed body serves names that are plural, such as Native v3 CRDs, as well as singular ones. The notice reads nothing from data/feature-status.yaml at runtime, since it is a page-level editorial statement. A build-time check reconciles the two instead: lifecycle-id binds a page to a feature, and the test fails when a page and the data file disagree. It is seeded with the contradiction that shipped in 3.33, where the release notes called native v3 CRDs generally available while the install page still called it a technology preview. Converts two pages as pilots, one of each form. The remaining pages follow in later changes.
Calico Cloud 24-1 replaced 23-2 as the published version, so the drift test now checks version-24-1 against the CE 3.24 line.
ctauchen
force-pushed
the
DOCS-3057-mechanism
branch
from
October 14, 2026 16:02
3425803 to
ede5b42
Compare
Every other front matter key on the site is snake_case, such as sidebar_label. Rename lifecycle-status, lifecycle-feature and lifecycle-id to match before any page beyond the pilots uses them.
The converter dropped admonition titles, so a lifecycle notice lost its feature name in llms.txt and the .md twins, and every deprecation notice lost "deprecation and removal notice". Keep a custom title in the label. The label also came from the alert color class rather than the admonition type, so notes were labeled SECONDARY and tips SUCCESS. Use the type instead.
Build the list of checked trees from the product versions files, so every versioned tree is checked, including OSS 3.32 and 3.31 and CE 3.22-2 and 3.21-2, and a new cut needs no edit here. Read each Calico Cloud tree's release line from its own variables.js. Read inline notices whose attributes are expressions or contain >, and fail on an inline notice with an id but no readable status instead of skipping it. Explain a failure on a feature marked confirmed: false. Fail the build on an unknown lifecycle front matter key, or on lifecycle_feature or lifecycle_id without lifecycle_status, since either would otherwise render no notice and pass every check.
A deprecation notice says the feature is still present and supported, which is false once the data file records it as removed, so the drift check no longer accepts that pairing. Fail the drift suite when it finds no declarations at all, rather than passing with no page-level cases. Correct the writer guidance on variables in lifecycle front matter: substitution there happens but is not reliable.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Technology preview and deprecation notices are hand-typed prose repeated across 133 pages in at least eight wordings. That is why notices outlive the status they describe, as DOCS-236, DOCS-616 and DOCS-375 all record, and as #3051 had to fix again. This adds one way to write them.
A page that is wholly about a feature declares the status in front matter and writes nothing in the body:
A new remark plugin places the notice directly after the page title, where every hand-written notice already sat. It inserts the component rather than building an admonition itself, so the front matter form and the hand-placed form render through the same code and cannot drift apart. A page that declares a status but has no title fails the build, as does a misspelled lifecycle key or a lifecycle_id without lifecycle_status, since either would otherwise render no notice.
When only part of an otherwise generally available page is affected, or the notice needs extra guidance such as what to migrate to, the component is used directly in the page.
Two decisions worth a reviewer's attention.
The feature name is the admonition title rather than the subject of a sentence. Four of the names in data/feature-status.yaml are plural, so a template like "X is a technology preview feature" cannot serve all of them without a grammar flag per feature.
The notice reads nothing from data/feature-status.yaml at runtime, because it is a page-level editorial statement and coupling it would make every page edit a data file edit. A test reconciles the two instead. The lifecycle_id binds a page to a feature, and the test fails when a page and the data file disagree for that tree's release. It runs in the Validate React code workflow, not the Netlify build, and main has no required checks, so a failure is reported on the PR but does not block a merge. It is seeded with the contradiction that shipped in 3.33, so it is exercised whatever the content tree currently looks like. Pages without an id are not checked, so a feature with no entry in the data file costs nothing. The trees checked come from each product's versions file, so every versioned tree is covered and a new cut needs no edit to the test.
Because the feature name is a title, this also fixes the Markdown twin converter, which dropped admonition titles from llms.txt and the .md twins. A custom title is now kept in the label, for example "WARNING: deprecation and removal notice", which also repairs the 72 existing deprecation notices that lost that phrase. The label now uses the admonition type rather than its color class, so notes are labeled NOTE instead of SECONDARY and tips TIP instead of SUCCESS.
Verification:
Two pages are converted as pilots, one of each form. They are in the next tree, so the links are on the next preview host, because static/_redirects sends next paths away from the main preview.
The remaining pages follow in later changes, one product per change.
Related: DOCS-2999.