Revisiting consistency in documenting features that were previously experimental

[VoxelMC]

📚 Subject area/topic

Experimental Features

📋 Page(s) affected (or suggested, for new content)

• View Transitions - Since is current, but doesn't mention experimental. https://docs.astro.build/en/guides/view-transitions/
• Astro Assets (<Image /> and <Picture />) - Inconsistent Since https://docs.astro.build/en/guides/images/
• Content Collections - Inconsistent `Since https://docs.astro.build/en/guides/content-collections/
• Prerender API (export const prerender = true | false) - No Since https://docs.astro.build/en/guides/server-side-rendering/#opting-in-to-pre-rendering-in-server-mode
• Dev Toolbar - No Since https://docs.astro.build/en/reference/configuration-reference/#dev-toolbar-options

📋 Description of content that is out-of-date or incorrect

Some features that have previously been added to Astro were first introduced as experimental. In doing so, the addition of these features was documented as experimental when first introduced. After the features were moved from experimental to officially supported, the documentation became inconsistent.

In the case of View Transitions, the transition:persist directive is documented to be introduced in astro@2.10.0. However, at this time, this would have been experimental.

• Should this be documented as astro@3.0.0, which was when the featured moved out of experimental?

In Astro Assets, the <Image /> component doesn't have a "since", while the <Picture /> tag is documented as astro@3.3.0. Moreover, some documented properties of the Image component are flagged as experimental, added in 3.3.0.

• How should docs handle documenting when something is experimental and when it moves from experimental to official support?

Essentially, the documentation doesn't account for when something was experimental (if applicable). Those using older versions may believe that a feature is available when it was only experimental then.

🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)

No response

[sarah11918]

These are all great observations @VoxelMC , and your gut reactions here have been spot on!

I would say that yes, we can update any "Since"'s to their official/non-experimental version numbers.

I would also say that anything missing a Since at all could have them added, yes!

I don't see anything on the images currently being marked as Experimental though? Can you point out specifically what you mean there.

Right now, the only things that are experimental are listed here: https://docs.astro.build/en/reference/configuration-reference/#experimental-flags and I don't think there is documentation outside of this page for any of those?

[sarah11918]

Just checking in on this issue @VoxelMC !

I'm confident saying that yes, anything that was at one point experimental but is no longer should have a Since/version that corresponds to when they were in the stable Astro core code (not introduced experimentally).

For future historians checking in on this issue, that's how we roll with our <Since /> component, and any updates to the docs to reflect that will be welcome!

(I don't immediately see what the problem is with the content collections nor images page from what you've linked, but the others do make sense to me, and updates to add/update the Since component are welcome!)

[sarah11918]

(lol, hit the wrong button! This issue is open!)

[VoxelMC]

Just checking in on this issue @VoxelMC !

I'm confident saying that yes, anything that was at one point experimental but is no longer should have a Since/version that corresponds to when they were in the stable Astro core code (not introduced experimentally).

For future historians checking in on this issue, that's how we roll with our <Since /> component, and any updates to the docs to reflect that will be welcome!

(I don't immediately see what the problem is with the content collections nor images page from what you've linked, but the others do make sense to me, and updates to add/update the Since component are welcome!)

Sounds good! I will propose some.changes the moment I have a chance to sit down and check if I haven't missed anything :)

As for experimental versions, will we be omitting those entirely?

[sarah11918]

I'm not sure what you mean about omitting experimental versions? Usually we do sequester anything experimental to either the config reference page for experimental flags, or in some cases an entire guide or API page devoted to the experimental feature. So, really where I expect this is even an issue is in a page (or config ref entry) that was experimental but is no longer so.

Can you give me an example of what falls under what you're asking so I can see what you mean?

[sarah11918]

Just a ping to see if you're still interested in this, @VoxelMC ! Seems like it would be great for consistency!

[sarah11918]

Just moving this up in the stack on the list! This would be a great help wanted initiative!

I think it would be a lot of work to go too far back for a lot of these, but as we prepare for Astro 5.0 before the end of the year and most of our users are actually on some version of 4.0, I think prioritizing features introduced in 4.x would be helpful and achievable.

If people want to get involved, you could do any combination of the following (and, tiny individual PRs would be fine! No need to get the whole thing done!)

• Look at our major feature pages like content collections, view transitions, internationalization etc. and identify properties that don't say "Added in:" (In docs, this will be a <Since /> component). If you find one that is conspicously missing, look up in Astro's Changelog which version it was added in, and add a Since component with the appropriate version.

• Start from the changelog and work backwards! Any time something "code" had been released ( e.g. inferRemoteSize), go look up its documentation and add a Since component if it's missing.

• Start from the reference and other API files and look for items without a Since component. These are the most referency pages, and if they are here, they are probably not documented formally in a guide (just explained how to use or shown in examples)

You can make a PR with **one single <Since / > that you find and verify!! No need to get fancy or do a lot of work!

You can find documentation on how to use this component inthe custom component reference in Astro Docs Docs