docs: add alpha, preview, legacy availability values#5130
docs: add alpha, preview, legacy availability values#5130Swimburger wants to merge 2 commits intomainfrom
Conversation
Document the newly supported x-fern-availability / availability values for OpenAPI endpoints and Fern Definitions: alpha, preview, legacy. Co-Authored-By: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ## Endpoints, types, and properties | ||
|
|
||
| Availability can be: | ||
| - `alpha` which means it is an early experimental release; will show an `Alpha` tag |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.
| - `in-development` which means it is being worked on; will show a `Beta` tag | ||
| - `pre-release` which means it is available; will show a `Beta` tag | ||
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag | ||
| - `preview` which means it is feature-complete but subject to change; will show a `Preview` tag |
There was a problem hiding this comment.
🚫 [vale] reported by reviewdog 🐶
[Microsoft.Contractions] Use 'it's' instead of 'it is'.
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag | ||
| - `preview` which means it is feature-complete but subject to change; will show a `Preview` tag | ||
| - `generally-available` which means it is stable and available for use; will show a `GA` tag | ||
| - `deprecated` which means it will be removed in the future; will show a `Deprecated` tag |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'in the future' that become outdated
|
🌿 Preview your docs: https://fern-preview-devin-1776986455-add-alpha-preview-legacy-availab.docs.buildwithfern.com/learn Here are the markdown pages you've updated: |
| | `pre-release` | Available | `Beta` | | ||
| | `preview` | Feature-complete but subject to change | `Preview` | | ||
| | `generally-available` | Stable and available for use | `GA` | | ||
| | `deprecated` | Will be removed in the future | `Deprecated` | |
There was a problem hiding this comment.
[FernStyles.Current] Avoid time-relative terms like 'in the future' that become outdated
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| | Value | Description | Tag | | ||
| | --- | --- | --- | | ||
| | `alpha` | Early experimental release | `Alpha` | | ||
| | `in-development` | Being worked on | `Beta` | | ||
| | `pre-release` | Available | `Beta` | | ||
| | `preview` | Feature-complete but subject to change | `Preview` | | ||
| | `generally-available` | Stable and available for use | `GA` | | ||
| | `deprecated` | Will be removed in the future | `Deprecated` | | ||
| | `legacy` | Superseded but still supported | `Legacy` | |
There was a problem hiding this comment.
🟡 Shared availability snippet not updated with new values, creating within-page inconsistency
Both changed pages include <Markdown src="/products/api-def/snippets/availability.mdx" /> at the bottom (lines fern/products/api-def/ferndef/availability.mdx:109 and fern/products/api-def/openapi/extensions/availability.mdx:42). The snippet at fern/products/api-def/snippets/availability.mdx:1 still lists only the old options: stable, generally-available, in-development, pre-release, deprecated, or beta. The new availability values alpha, preview, and legacy are added to the tables at the top of both pages but are absent from the included snippet. A user reading either page would see the new values documented in the "Endpoints" section, then scroll to the "Sections" section and find a different, incomplete set of options. This also violates the AGENTS.md rule: "Before creating new content, search the repo for existing pages that already cover the topic. Prefer updating over duplicating."
Prompt for agents
The shared snippet at fern/products/api-def/snippets/availability.mdx is included by both changed pages (ferndef/availability.mdx line 109 and openapi/extensions/availability.mdx line 42) under their Sections headings. It currently lists availability options as: stable, generally-available, in-development, pre-release, deprecated, or beta. This needs to be updated to also include the new values: alpha, preview, and legacy. Update line 1 of the snippet to include all availability options that are now documented in the endpoint-level tables.
Was this helpful? React with 👍 or 👎 to provide feedback.
Self-reviewDiff is small and the docs match what's actually shipping in fern#15320 + fern-platform#10027.
This PR can land independently — it's just docs and the values it describes are valid the moment fern#15320 ships. |
2 participants
Summary
Document the newly supported
x-fern-availability/availabilityvalues —alpha,preview, andlegacy— for OpenAPI endpoints and Fern Definitions. Companion PRs add support to the IR / SDK generation path (fern#15320) and the FDR schema (fern-platform#10027).Two pages updated:
fern/products/api-def/openapi/extensions/availability.mdx— expanded the endpoint options list from 3 values to 6, with a short explanation and the rendered tag for each.fern/products/api-def/ferndef/availability.mdx— same additions to the Fern Definition availability list.The
docs.ymlsection-level availability snippet is intentionally not updated here — docs.yml uses FDR'sNavigationV1Availabilityenum, which does not yet include these values. That will land separately after fern-platform#10027 merges and a newfdr-sdkships.Review & Testing Checklist for Human
Risk: green (copy-only change, no config or component changes).
Notes
Intentionally leaving
snippets/availability.mdxalone — it documents the section/docs.ymlsurface wherealpha/preview/legacyare not yet valid.Link to Devin session: https://app.devin.ai/sessions/dfd46458269a401d82862980e905e9a2
Requested by: @Swimburger