[v6] stabilize experimental.preserveScriptOrder option

astro.sidebar.ts

@@ -147,7 +147,6 @@ export const sidebar = [
 					'reference/experimental-flags/live-content-collections',
 					'reference/experimental-flags/client-prerender',
 					'reference/experimental-flags/content-intellisense',
-					'reference/experimental-flags/preserve-scripts-order',
 					'reference/experimental-flags/heading-id-compat',
 					'reference/experimental-flags/static-import-meta-env',
 					'reference/experimental-flags/chrome-devtools-workspace',

src/content/docs/en/guides/upgrade-to/v6.mdx

@@ -371,6 +371,37 @@ prefetch('/about');
 
 <ReadMore>Learn more about [prefetching](/en/guides/prefetch/).</ReadMore>
 
+### Experimental Flags
+
+The following experimental flags have been removed in Astro v5.0 and these features are available for use:
+
+- `thing 1`
+
+Additionally, the following experimental flags have been removed and **are now the default or recommended behavior in Astro v5.0**.
+
+- `experimental.preserveScriptOrder` (See below for breaking changes to [default `<script>` and `<style>` behavior](#changed-script-and-style-tags-are-rendered-in-the-order-they-are-defined).)
+
+The following experimental flags have been removed and **their corresponding features are not part of Astro v5.0**.
+
+- `thing 2`
+
+Remove these experimental flags if you were previously using them, and move your `env` configuration to the root of your Astro config:
+
+```js del={5} title="astro.config.mjs"
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  experimental: {
+    preserveScriptOrder: true,
+  },
+})
+```
+
+These features are all available by default in Astro v5.0.
+
+<ReadMore>Read about these exciting features and more in [the v6.0 Blog post](https://astro.build/blog/astro-6/).</ReadMore>
+
+
 ## Changed Defaults
 
 Some default behavior has changed in Astro v5.0 and your project code may need updating to account for these changes.
@@ -404,6 +435,46 @@ export default defineConfig({
 
 <ReadMore>Learn more about [Internationalization routing](/en/guides/internationalization/#routing).</ReadMore>
 
+### Changed: `<script>` and `<style>` tags are rendered in the order they are defined
+
+<SourcePR number="14480" title="feat: stabilize experimental preserveScriptOrder option"/>
+
+In Astro v5.5, the `experimental.preserveScriptOrder` flag was introduced to render multiple `<style>` and `<script>` tags in the same order as they were declared in the source code. Astro used to reverse their order in your generated HTML output. This could give unexpected results, for example, CSS styles being overridden by earlier defined style tags when your site was built.
+
+Astro 6.0 removes this experimental flag and makes this the new default behavior in Astro: scripts and styles are now rendered in the order defined in your code.
+
+#### What should I do?
+
+If you were previously using this experimental feature, you must [remove this experimental flag from your configuration](#experimental-flags) as it no longer exists.
+
+Review your `<script>` and `<style>` tags to make sure they behave as desired. You may need to reverse their order:
+
+```astro title="src/components/MyComponent.astro" del={4,10,15,19} ins={5,11,16,20}
+<p>I am a component</p>
+<style>
+  body {
+    background: red;
+    background: yellow;
+  }
+</style>
+<style>
+  body {
+    background: yellow;
+    background: red;
+  }
+</style>
+<script>
+    console.log("hello")
+    console.log("world")
+</script>
+<script>
+    console.log("world!")
+    console.log("hello!")
+</script>
+```
+
+<ReadMore>Read more about [using `script`](/en/guides/client-side-scripts/) and [`style`](/en/guides/styling/) tags.</ReadMore>
+
 ## Breaking Changes
 
 The following changes are considered breaking changes in Astro v5.0. Breaking changes may or may not provide temporary backwards compatibility. If you were using these features, you may have to update your code as recommended in each entry.