[draft] adding build image policies for Workers Builds and Pages

src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx

@@ -0,0 +1,17 @@
+---
+title: Build image policies for Workers Builds and Cloudflare Pages
+description: Workers Builds and Cloudflare Pages now have documented build image policies outlining deprecation timelines and version update procedures.
+products:
+  - workers
+date: 2025-12-01
+---
+
+We've published build image policies for [Workers Builds](/workers/ci-cd/builds/build-image/#build-image-policy) and [Cloudflare Pages](/pages/configuration/build-image/#build-image-policy) that establish:
+
+- **Minor version updates**: Default versions are updated to the latest available minor version without notice 
+- **Major version updates**: When language runtimes or tools reach end-of-life, we update to the next stable LTS version with at least 3 months advance notice via Changelog and dashboard notifications
+- **Build image version deprecation** (Pages only): Build image versions are supported for at least 2 years and receive 6 months notice before removal via Changelog, dashboard notifications, and email
+
+To prepare for updates and avoid unexpected build failures:
+- Monitor the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), the dashboard, and your email for announcements
+- [Override default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) if you need to maintain specific versions for your applications

src/content/docs/pages/configuration/build-image.mdx

@@ -105,3 +105,41 @@ The following features are not currently supported when using the v3 build syste
 Cloudflare Pages builds are run in a [gVisor](https://gvisor.dev/docs/) container.
 
 <PagesBuildEnvironment />
+
+
+## Build Image Policy
+
+New build image versions bring improvements to tooling, security, and performance.
+
+### Image Version Deprecation
+
+Build image versions are supported for at least 2 years from their initial release before a deprecation is announced.
+
+**Deprecation timeline**: We provide 6 months notice before removing support for a build image version.
+
+**Deprecation process**:
+1. **Announcement** via [Cloudflare Changelog](https://developers.cloudflare.com/changelog/)
+2. **Deprecation warnings** displayed in dashboard for projects using the build image version scheduled for deprecation
+3. **Email notifications** to project owners 
+4. **Final removal** on the announced date:
+   - The deprecated image version will no longer be available for selection
+   - Projects that have not migrated will be automatically upgraded to the latest supported version
+
+### Default Version Updates
+
+Default versions of languages and tools are updated as they reach end-of-life (EOL). These updates only apply if you have not [overridden the default version](/pages/configuration/build-image/#override-default-versions).
+
+- **Minor version updates**: Updated to the latest available minor version without notice.
+
+- **Major version updates**: Updated to the next stable, long-term support (LTS) version with at least 3 months advance notice via:
+  - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/)
+  - Dashboard notifications to projects that will receive the default version update
+
+To maintain a specific version and avoid automatic updates, [override the default version](/pages/configuration/build-image/#override-default-versions).
+
+### Best Practices
+
+To avoid unexpected build failures:
+- **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications
+- **Plan for migration** when you receive deprecation notices
+- **Pin specific versions** of critical dependencies by [overriding default versions](/pages/configuration/build-image/#override-default-versions) to maintain full control over when versions change

src/content/docs/workers/ci-cd/builds/build-image.mdx

@@ -88,3 +88,24 @@ Workers Builds are run in the following environment:
 | --------------------- | ------------ |
 | **Build Environment** | Ubuntu 24.04 |
 | **Architecture**      | x86_64       |
+
+
+## Build Image Policy
+
+### Default Version Updates
+
+Default versions of languages and tools are updated as they reach end-of-life (EOL). These updates only apply if you have not [overridden the default version](/pages/configuration/build-image/#override-default-versions).
+
+- **Minor version updates**: Updated to the latest available minor version without notice.
+
+- **Major version updates**: Updated to the next stable, long-term support (LTS) version with at least 3 months advance notice via:
+  - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/)
+  - Dashboard notifications to projects that will receive the default version update
+
+To maintain a specific version and avoid automatic updates, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions).
+
+### Best Practices
+
+To avoid unexpected build failures:
+- **Monitor announcements** via the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications
+- **Pin specific versions** of critical dependencies by [overriding default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) to maintain full control over when versions change