Skip to content
Merged
64 changes: 63 additions & 1 deletion .vortex/docs/content/development/composer.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -208,6 +208,66 @@ closely at the scaffold files that core updates, such as `web/index.php` and
overwrites it. When a core release changes `.htaccess`, port the change by
hand.

### Release cooldown

`composer update` and `composer require` skip any tagged release published
less than 7 days ago. A compromised release is often detected and pulled
within days, so the delay keeps it out of your project. Branch versions
such as `dev-main` change with every commit, so the cooldown leaves them
alone. With a `composer.lock`, `composer install` installs what the lock
pins, so the cooldown doesn't affect it.

**Vortex** sets the delay in the `cooldown` section of
[`config.policy`](https://getcomposer.org/doc/06-config.md#policy):

```json
"cooldown": {
"period": "7 days",
"ignore": {
"drupal/core": "Drupal core security releases need to be applied immediately.",
"drupal/core-*": "Drupal core security releases need to be applied immediately."
}
}
```

The `ignore` entries exempt the Drupal core packages, so a core security
release installs on the day it's published. `drupal/core-recommended` pins
exact versions of the packages core depends on, such as Symfony. The
cooldown still holds back a pinned version younger than 7 days. Composer
then resolves the older core release, or fails when your constraint needs
the new one. It reports the versions it holds back:

```text
3 package version(s) withheld by the cooldown policy (run with -vv to list them).
```

To install a release before it's 7 days old, such as an urgent security
fix, add `--no-cooldown` to the update command:

<Tabs>
<TabItem value="ahoy" label="Ahoy" default>
```shell
ahoy composer update "drupal/core-*" --with-dependencies --no-cooldown
```
</TabItem>
<TabItem value="docker-compose" label="Docker Compose">
```shell
docker compose exec cli composer update "drupal/core-*" \
--with-dependencies --no-cooldown
```
</TabItem>
</Tabs>

The cooldown applies again on your next full `composer update`. Until the
releases you installed are 7 days old, that update can move an indirect
dependency back to an older release. [Dependency
bumping](#dependency-bumping) raises the constraint of each package you
require directly, so those packages keep the release you installed. Add
`--no-cooldown` to each full update until then.

To change the delay, edit `period`, such as `"3 days"`. Set it to `null` to
turn the cooldown off. The cooldown requires Composer 2.11 or later.

### Dependency bumping

[Dependency bumping](https://getcomposer.org/doc/03-cli.md#bump) raises the
Expand Down Expand Up @@ -751,7 +811,9 @@ following keys:
vulnerabilities stay visible without breaking reproducible builds.
Abandoned packages show up in the report without failing it. ➡️ See
[Dependency audit](security/dependency-audit.mdx) for the option values,
how to ignore advisories and the CI integration.
how to ignore advisories and the CI integration. The `cooldown` section
holds back releases younger than 7 days, except Drupal core. ➡️ See
[Release cooldown](#release-cooldown).
- [`bump-after-update`][bump-after-update]:
Runs `composer bump` after every `composer update`, which raises the
version constraints in `composer.json` to the installed versions.
Expand Down
10 changes: 10 additions & 0 deletions .vortex/docs/content/development/dependency-updates.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,9 @@ after.

Drupal core has no delay, so a core security release is proposed on the next
daily run. Its rule in `renovate.json` carries a `description` that says so.
Composer's [release cooldown](composer.mdx#release-cooldown) exempts the
core packages too. Renovate's update of `composer.lock` then fails only
when the release pins a dependency younger than 7 days.

#### Registries without release dates

Expand Down Expand Up @@ -170,6 +173,13 @@ after it reads the advisory. The PR skips the minimum release age, the
group's schedule and the limit on open PRs. It updates the affected
dependency to the lowest release that fixes the advisory.

Composer's [release cooldown](composer.mdx#release-cooldown) still applies
when Renovate updates `composer.lock`. When the fix, or a dependency it
pins, is younger than 7 days, the lock update fails. Renovate then reports
an artifact update problem on the PR. To apply the fix, check out the PR
branch, run `ahoy composer update` for the package with
`--with-dependencies --no-cooldown` and push the result.

Advisory PRs carry the `Dependencies` and `Security` labels, so they stand
apart from routine updates. The `vulnerabilityAlerts` setting in
`renovate.json` sets the labels:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,8 @@ rest, including the `malware` and `cooldown` policies and the per-entry
:::note Composer 2.10+

`config.policy` requires Composer 2.10 or newer, which ships in the
**Vortex** container images. On older Composer versions, use the legacy
**Vortex** container images. The `cooldown` section requires Composer 2.11
or newer. On older Composer versions, use the legacy
`config.audit` keys (`block-insecure`, `abandoned`) instead. Composer 2.10
and newer still read those keys, but only when the matching `config.policy`
section is absent.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,13 @@
},
"abandoned": {
"audit": "report"
},
"cooldown": {
"period": "7 days",
"ignore": {
"drupal/core": "Drupal core security releases need to be applied immediately.",
"drupal/core-*": "Drupal core security releases need to be applied immediately."
}
}
},
"sort-packages": true
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@@ -131,38 +131,38 @@
@@ -138,38 +138,38 @@
"[web-root]/update.php": false
},
"locations": {
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
@@ -131,38 +131,38 @@
@@ -138,38 +138,38 @@
"[web-root]/update.php": false
},
"locations": {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@
},
"bump-after-update": true,
"discard-changes": true,
@@ -169,6 +176,17 @@
@@ -176,6 +183,17 @@
"patchLevel": {
"drupal/core": "-p2"
},
Expand Down
7 changes: 7 additions & 0 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,13 @@
},
"abandoned": {
"audit": "report"
},
"cooldown": {
"period": "7 days",
"ignore": {
"drupal/core": "Drupal core security releases need to be applied immediately.",
"drupal/core-*": "Drupal core security releases need to be applied immediately."
}
}
},
"sort-packages": true
Expand Down
Loading