diff --git a/src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx b/src/content/changelog/workers/2025-12-01-build-image-policies-dev-plat.mdx new file mode 100644 index 000000000000000..2f37464b750ac22 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/src/content/docs/pages/configuration/build-image.mdx b/src/content/docs/pages/configuration/build-image.mdx index f7c840fa048ae63..56eb636c8bc9dad 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/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. + + +## 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 \ No newline at end of file diff --git a/src/content/docs/workers/ci-cd/builds/build-image.mdx b/src/content/docs/workers/ci-cd/builds/build-image.mdx index e49d9c48993c9d0..a0187bc6711e33a 100644 --- a/src/content/docs/workers/ci-cd/builds/build-image.mdx +++ b/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 \ No newline at end of file