feat: add compatibility-date

Author: shyim

products/cli/extension-commands/configuration.md

@@ -12,6 +12,8 @@ Many configurations can be changed using a `.shopware-extension.yml` file in the
 Here is an example of a `.shopware-extension.yml` file:
 
 ```yaml
+compatibility_date: '2026-02-11'
+
 build:
   extraBundles:
     - path: src/Foo
@@ -42,6 +44,20 @@ validation:
 
 When you edit that file in an editor, you will get autocompletion and hints for the available options.
 
+## compatibility_date
+
+You can define a `compatibility_date` in `.shopware-extension.yml`:
+
+```yaml
+compatibility_date: '2026-02-11'
+```
+
+The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.
+
+- Format: `YYYY-MM-DD`
+- If the field is missing, Shopware CLI uses `2026-02-11` as fallback
+- When missing, Shopware CLI logs a warning during config loading
+
 ## Environment variables
 
 Additionally, you can set environment variables to change the behavior of the CLI. The following environment variables are available:

products/cli/project-commands/build.md

@@ -105,6 +105,8 @@ MJML compilation requires the `mjml` package to be installed via NPM in your bui
 You can configure the build process with a `.shopware-project.yml` file. The following options are available:
 
 ```yaml
+compatibility_date: '2026-02-11'
+
 build:
   # Browserlist configuration for Storefront
   browserslist: 'defaults'
@@ -134,6 +136,20 @@ build:
       - custom/static-plugins
 ```
 
+## compatibility_date
+
+You can define a `compatibility_date` in `.shopware-project.yml`:
+
+```yaml
+compatibility_date: '2026-02-11'
+```
+
+The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.
+
+- Format: `YYYY-MM-DD`
+- If the field is missing, Shopware CLI uses `2026-02-11` as fallback
+- When missing, Shopware CLI logs a warning during config loading
+
 ## Supporting bundles
 
 Shopware CLI automatically detects plugins and Apps. Custom bundles (classes that extend bundle class from Shopware) cannot be automatically detected as Shopware CLI does not execute any PHP code.