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 only documented in their experimental flag section of the configuration 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!

Read more about why we document experimental features differently!

Where to add your documentation

Documentation to the configuration reference page is added in the main astro repo to astro/packages/astro/src/@types/astro.ts. You can find the section for experimental flags by searching for this line: @name Experimental Flags.

JSDoc format

Add a new entry with the following structure:

/**
     * @docs
     * @name experimental.feature
     * @type {boolean}
     * @default `false`
     * @version 4.x.0
     * @description
     *
     * This feature [does/allows you to...]
     *
     * To enable this feature, add the experimental flag in your Astro config:
     *
     * ```js
     * {
     *   experimental: {
     *     featureName: true,
     *   },
     * }
     * ```
     *
     * Describe any required configuration, as well as basic usage here.
     * It's OK if this is 100 lines or so!
     * This will be the only documentation in docs!
     * The RFC will do most of the docs "heavy lifting."
     *
     * For a complete overview, and to give feedback on this experimental API,
     * see the [Feature RFC](https://github.com/withastro/roadmap/blob/actions/proposals/00xx-feature.md).
     */
    actions?: boolean;

What to include in the description

Add the following underneath the @description tag, in order:

1. A short description of what the feature does or allows you to do. (1 - 4 sentences)

2. To enable this feature, add the experimental flag in your Astro config: (1 line)

3. 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 output config:

     {
      output: 'hybrid', // or 'server'
      experimental: {
       featureName: true,
      },
     }

4. 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.”

5. 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.

6. The following two lines to direct readers to the RFC for your feature, replacing the name and link with your own. (2 lines)

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

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!

Now, your documentation will live somewhere else in Astro Docs (Team Docs will guide you through a separate docs PR!) and the experimental flag will be removed from our Configuration Reference page.

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:

1. 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)

2. 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.

3. If you were previously using this feature, please remove the experimental flag from your Astro config: (1 line)

4. 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,
     }
   })

5. 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!)