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 00000000000000..9dd5656383852f --- /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) and [Cloudflare Pages](/pages/configuration/build-image) that establish: + +- **Minor version updates** happen automatically without notice +- **Major version updates** require at least 3 months advance notice when language runtimes or tools approach their end-of-life dates +- **Build image version deprecation** (Pages only): Build image versions are supported for at least 2 years and will receive at least 6 months notice before removal + +When deprecations or major updates are announced, you'll receive notifications via the Cloudflare Changelog, dashboard notifications, and email. + +To avoid unexpected build failures, we recommend [pinning specific versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) for production applications and monitoring the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/), as well as the dashboard, and your emails. \ 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 f7c840fa048ae6..85800c9b97e791 100644 --- a/src/content/docs/pages/configuration/build-image.mdx +++ b/src/content/docs/pages/configuration/build-image.mdx @@ -105,3 +105,38 @@ 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 before a deprecation is announced. + +**Deprecation timeline**: We provide at least 6 months notice before removing support for a build image version. + +**Deprecation process**: +1. **Announcement** via [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) and dashboard notifications +2. **Deprecation warnings** displayed prominently in dashboard for affected projects +3. **Email notifications** to project owners +4. **Final removal** on the announced date; projects using the deprecated image will be automatically upgraded to the next supported version + + +### Default Version Updates + +Default versions of languages and tools are updated regularly to their latest stable releases. + +- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions). + +- **Major version updates**: When a language runtime or tool approaches its end-of-life (EOL) date, e.g. Node.js, we update to the latest supported version. We will provide at least 3 months advance notice via + - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) + - Dashboard notification to affected projects upon announcement + +### 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) \ 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 e49d9c48993c9d..e58bd2b8c99809 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,22 @@ 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 regularly to their latest stable releases. + +- **Minor version updates**: Default versions are updated to the latest minor version without notice (e.g., Node.js 22.15.0 → 22.16.0). If you need a specific minor version, [override the default version](/workers/ci-cd/builds/build-image/#overriding-default-versions). + +- **Major version updates**: When a language runtime or tool approaches its end-of-life (EOL) date, e.g. Node.js, we update to the latest supported version. We will provide at least 3 months advance notice via + - [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) + - Dashboard notification to affected projects upon announcement + +### Best Practices + +To avoid unexpected build failures: +- **Pin specific versions** for production applications by [overriding default versions](/workers/ci-cd/builds/build-image/#overriding-default-versions) +- Monitor the [Cloudflare Changelog](https://developers.cloudflare.com/changelog/) for upcoming updates