Adding docs for experimental flags

Features released behind an experimental flag allow our developers to work quickly, respond to feedback, and even change features entirely with as little disruption to the Astro community as possible.

These features are not required to follow our normal semantic versioning rules and may introduce breaking changes without notice. Therefore, extra care must be taken when documenting.

Documenting experimental features

Since these features may change and even break several times during development, experimental features are only documented in the Experimental Features section of the reference page.

Only when a feature is no longer experimental do we add documentation and reference it within other pages. This gives us the greatest flexibility for things to change and evolve, as most experimental features do!

Where to add your documentation

In addition to providing a changeset message for your implementation PR in your implementation PR, you will add documentation for your experimental feature in a new page located in the following directory: src/content/docs/en/reference/experimental-flags/.

What to include in the changeset

The changeset is for introducing your new feature to Astro users for the first time. It’s purpose is to let them know that the feature exists and provide them with enough information to decide whether they would like to try it… and we hope they will try it! We release experimental features so we can more easily respond to feedback while developing the feature, including making breaking changes when necessary. This means that some hype or marketing speak is allowed because we want to encourage users who have a genuine need or interest in this feature to try it.

Use the following template for your changeset:

“Adds support for experimental [feature]”
A short description of what the feature does or allows you to do. (1 - 4 sentences)
To enable this feature, add the experimental flag in your Astro config: (1 line)
A minimal code example showing your experimental feature flag set to true. (code block)
```
{
 experimental: {
  featureName: true,
 },
}
```
- Include any required configuration that must be also be set. (if applicable)
- For example, if your feature requires on-demand rendering, include the adapter config:
```
{
 adapter: 'netlify', // the adapter of your choice
 experimental: {
  featureName: true,
 },
}
```
Mention general requirements/limitations or situations where this feature does not work. (if applicable)
- Do not be overly specific, but do let the reader know if there are general requirements.
- For example, “This feature is not available on prerendered pages.”
Minimal usage description and examples (aim for 100 lines max)
- Think of this as your traditional documentation section.
- Keep explanations short, focused on getting someone started.
- If included, stick to showing only common, basic examples.
- Do not try to cover every case/example.
- No strict maximum length; take the space you truly need.

The following lines to direct readers to both the experimental feature page in docs, and the RFC for your feature, replacing the name and link with your own. (2 lines)

For more information on enabling and using this feature in your project, see the [Experimental CSP docs](link to experimental feature page in docs).

For a complete overview, and to give feedback on this experimental API, see the [Feature Name RFC](link to RFC proposal).

What to include in the experimental feature page docs

Introduction

Write your documentation assuming that people know what the general feature area (e.g. fonts, Content Security Policy) is and how it works. (They may not, but the docs team can help identify and fill in gaps to match the level of the rest of our docs re: how much of third-party or non-Astro specific topics we do/don’t explain.) Provide a link to a reputable source (e.g. MDN web docs) instead of explaining general web development ideas in detail.

This experimental feature allows you to use fonts from your filesystem and various font providers (eg. Google, Fontsource, Bunny) through a unified, fully customizable, and type-safe API.

Web fonts can impact page performance at both load time and rendering time. This API helps you keep your site performant with automatic [web font optimizations](https://web.dev/learn/performance/optimize-web-fonts) including preload links, optimized fallbacks, and opinionated defaults.

Configuring the experimental flag

Follow the format used for the changeset to show readers how to enable your experimental feature. Be sure to include a realistic configuration example, especially if your feature requires a configuration object with multiple properties, or requires other changes to a project’s configuration to work.

Astro-specific explanations

Focus on “things only we could / would write” about this feature and topic area. In other words, it is not your responsibility to document the general web development concept, but rather what someone needs to know about enabling, configuring, and using your specific new feature in their Astro project. This can include:

How it’s configured and used in your Astro project, and how to make any additional configuration decisions.
What it does (or doesn’t yet) do for your Astro project. (e.g. your feature may only focus on one particular aspect of a common web feature)
How you add/incorporate it with an existing project, and when you would/wouldn’t.
Any tradeoffs or things to check for in your Astro project that enabling this might affect.

Common usage examples

Provide examples of your feature configured and used, and show common, realistic use whenever possible. Someone may make different choices in their own project, but seeing a complete, correct example can let them know that their use “seems similar.”

Full API reference

Any value that can be configured, prop that can be passed, or helpful function that can be used must be fully documented with a brief example. You can use existing API reference / configuration docs as an example for format. Do not worry that these are subject to change. Document them as they exist at the time of release, and always come back and update these docs as your feature develops.

Breaking Changes (while still experimental)

Updates to experimental features are always a patch update to astro. However, unlike other patch updates, these may contain breaking changes.

It is important to both alert users of the feature of this breaking change, but at the same time, not alarm Astro users who are not using the feature!

Use the following model for your changeset:

---
"astro": patch
---

**BREAKING CHANGE to the experimental Container API only**

// rest of changeset

Unflagging an experimental feature

Congratulations, your feature is ready for release!

Changeset

After removing your experimental documentation from astro.ts completely, the biggest docs task for this PR will be the changeset .md file that describes this PR for the CHANGELOG.

Create a changeset using the following structure:

---
"astro": minor
---

The `myFeature` feature introduced behind a flag in [vx.x.0](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md#xx0) is no longer experimental and is available for general use.

// Hype your feature!
// Use content from the original changeset and docs `@description`
This [feature description] allows you to ....

If you were previously using this feature, please remove the experimental flag from your Astro config:

```diff
import { defineConfig } from 'astro'

export default defineConfig({
-  experimental: {
-    myFeature: true,
-  }
})
```

If you have been waiting for stabilization before using this [feature description], you can now do so.

Please see [the specific page in docs](https://docs.astro.build/en/my-feature/) for more about this feature.

What to include in the changeset

Add the following underneath the frontmatter, in order:

The [feature description] introduced behind a flag in [vx.x.0](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md#xx0) is no longer experimental and is available for general use. (1 line)
Reused content from the experimental release changeset, as well as the @description from your experimental flag’s documentation in astro.ts. (aim for 100 lines max)
- Remember, for some readers this is the (only) feature release! Be as descriptive as you were when it was experimental!
- This “introduces” your feature for the first time.
- This can include basic configuration, usage, and examples.
- Be sure to check for accuracy, and update as necessary to reflect the current state of the feature.
- No strict maximum length; take the space you truly need.
If you were previously using this feature, please remove the experimental flag from your Astro config: (1 line)

A minimal diff code example showing your experimental feature flag removed from Astro config. (code block)

import { defineConfig } from 'astro'

export default defineConfig({
  experimental: {
    myFeature: true,
  }
})

The following lines to emphasize stability and direct readers to the documentation for feature, replacing the name and link with your own. (2 lines)

If you have been waiting for stabilization before using this [feature description], you can now do so.

Please see [the specific page in docs](https://docs.astro.build/en/my-feature/) for more about this feature.

Why we document differently

The development of these features emphasizes responsiveness and experimentation, so it is difficult to keep documentation up to date and translated. In some cases, experimental features behind a flag come with little or no documentation at all because we are not guaranteeing any stability: neither how, nor that, it works! We are happy to have people use and test these features, but our goal is building and not delivering at this stage of development.

In fact, the best resource for experimental features is the RFC (request for consideration) proposal document and discussion thread. This allows a reader to follow the progress of a feature’s intention, and how its implementation may have changed over time. This also allows engagement from the community, providing a place for questions and feedback before decisions are finalized.

Other reasons for not documenting experimental features in regular docs pages include:

Removing the burden of the feature developer to write documentation to the standards and conventions of Astro Docs. The RFC proposal documents evolve, and are added to (not revised) as the feature changes. Astro docs must contstantly update to only show the most current, accurate information.
Many people choose to wait until experimental features are stable before trying them. Keeping the docs limited to only the latest stable version of Astro’s fully-supported features is less confusing for most people.
Astro docs regularly receives PRs to update and correct information as they discover errors. Our repository activity is extremely high, and any perceived ommission or imperfection in our docs is noticed by our community adds extra workload to our docs team. While a feature may be experimental, docs itself is expected to be a stable, polished project. We can only achieve this once a feature has stabilized.
The lack of official documentation sets appropriate expectations surrounding support. Issues and support questions can be pointed to the RFC discussions instead of GitHub or Discord. It is not an “issue” if something isn’t working in an experimental feature. It’s not necessarily intended to work perfectly yet! But, getting feedback about a feature’s performance or behaviour in the discussion thread is very helpful to the developers.

And lastly, there’s some benefit to experimental features feeling… experimental! Insider secrets! I have to go into Ben’s mind to get the docs! I can participate in a roadmap discussion! We want our community to feel involved in the process whenever possible, as part of the team. (And, if we have to go ask Ben how this works, then our community “gets to”, too!)