Adds cooldown options to dependabot options reference

content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md

@@ -222,8 +222,8 @@
 
 By default, a group will include all types of dependencies.
 
 * Use `development` to include only dependencies in the "Development dependency group".
 * Use `production` to include only dependencies in the "Production dependency group".
 
 ### `patterns` and `exclude-patterns` (`groups`)
 
@@ -637,12 +637,12 @@
 
 #### Versioning tag glossary
 
 * **`alpha`:** Early version, may be unstable and have incomplete features.
 * **`beta`:** More stable than alpha but may still have bugs.
 * **`canary`:** Regularly updated pre-release version for testing.
 * **`dev`:** Represents development versions.
 * **`experimental`:** Versions with experimental features.
 * **`latest`:** The latest stable release.
 * **`legacy`:** Older or deprecated versions.
 * **`next`:** Upcoming release version.
 * **`nightly`:** Versions built nightly; often includes the latest changes.
@@ -663,7 +663,7 @@
 >
 > * Bundler{% ifversion dependabot-updates-cargo-private-registry-support %}
 > * Cargo{% endif %}
 > * Docker
 > * Gradle
 > * Maven
 > * Npm
@@ -737,3 +737,127 @@
 The `url` parameter defines where to access a registry. When the optional `replaces-base` parameter is enabled (`true`), {% data variables.product.prodname_dependabot %} resolves dependencies using the value of `url` rather than the base URL of that specific ecosystem.
 
 {% data reusables.dependabot.dependabot-replaces-base-nuget %}
+
+## `cooldown` {% octicon "versions" aria-label="cooldown" height="24" %}
+
+Defines a **cooldown period** for dependency updates to delay updates for a configurable number of days. This feature enables dependabot users to customize how often they receive new version updates, offering greater control over update frequency.
+
+> [!NOTE]
+> Cooldown is not applicable for security updates.
+
+### **How Cooldown Works**
+
+* When Dependabot runs updates as per defined schedule, it checks the **cooldown settings** to determine if new release for dependency is still within its cooldown period.  
+* If new version release date is within the cooldown period, dependency version update is **filtered out** and will not be updated until the cooldown period expires.  
+* Once the cooldown period ends for new version, the dependency update proceeds based on the standard update strategy defined in `dependabot.yml`.
+
+Without **`cooldown`** (default behaviour): {% data variables.product.prodname_dependabot %}
+
+* Dependabot checks for updates according to the scheduled defined via `schedule.interval`.  
+* All new versions are considered for updates **immediately**.  
+
+With **`cooldown`** enabled:
+
+* Dependabot checks for updates based on the defined `schedule.interval` settings.  
+* **Releases within the cooldown period are ignored.**  
+* Dependabot updates the dependency to the latest available version **that are no longer in cooldown period** following the configured `versioning-strategy`.
+
+### **Cooldown Configuration**
+
+| Parameter | Description |
+|-----------|-------------|
+| `default-days` | **Default cooldown period for dependencies** without specific rules (optional). |
+| `semver-major-days` | Cooldown period for **major version updates** (optional, applies only to SEMVER-supported package managers). |
+| `semver-minor-days` | Cooldown period for **minor version updates** (optional, applies only to SEMVER-supported package managers). |
+| `semver-patch-days` | Cooldown period for **patch version updates** (optional, applies only to SEMVER-supported package managers). |
+| `include` | List of dependencies to **apply cooldown** (up to **150 items**). Supports wildcards (`*`). |
+| `exclude` | List of dependencies **excluded from cooldown** (up to **150 items**). Supports wildcards (`*`). |
+
+### **semver versioning**
+
+| Package Manager        | SEMVER Supported |
+|-----------------------|------------------|
+| **Bundler**           | Yes              |
+| **Bun**               | Yes              |
+| **Cargo**             | Yes              |
+| **Composer**          | Yes              |
+| **Devcontainers**     | No               |
+| **Docker**            | No               |
+| **Docker Compose**    | No               |
+| **Dotnet SDK**        | Yes              |
+| **Elm**               | Yes              |
+| **Github Actions**    | No               |
+| **Gitsubmodule**      | No               |
+| **Gomod (Go Modules)**| Yes              |
+| **Gradle**            | Yes              |
+| **Helm**              | No               |
+| **Hex (Hex)**         | Yes              |
+| **Maven**             | Yes              |
+| **NPM and Yarn**      | Yes              |
+| **Pip**               | Yes              |
+| **Pub**               | Yes              |
+| **Swift**             | Yes              |
+| **Terraform**         | No               |
+| **UV**                | Yes              |
+
+> [!NOTE]
+>
+> * If `semver-major-days`, `semver-minor-days`, or `semver-patch-days` are not defined, `default-days` settings take precedence for cooldown based updates.
+> * `semver-major-days`, `semver-minor-days`, and `semver-patch-days` are only applicable for [supported package managers](#semver-versioning).
+> * The `exclude` list always take precedence over the `include` list. If a dependency is specified in both lists, it is excluded from cooldown and will be updated immediately.
+
+### **Cooldown settings limitations**
+
+* `days` must be between 1 and 90.
+* Maximum allowed items limit in `include` and `exclude` list is 150 each.
+
+### **Example `dependabot.yml` with cooldown**
+
+```yaml copy
+
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    cooldown:
+      default-days: 5
+      semver-major-days: 30
+      semver-minor-days: 7
+      semver-patch-days: 3 
+      include:
+        - "requests"
+        - "numpy"
+        - "pandas*"
+        - "django"
+      exclude:
+        - "pandas"
+```
+
+### **Expected Behavior**
+
+Cooldown will be active for dependencies `requests`, `numpy` and dependencies starting with `pandas`, and `django`.  Dependency with exact name `pandas` will be excluded from cooldown based updates as it is present in **exclude** list.
+
+#### **Update days**
+
+Updates to new versions for included dependencies will be deferred as following:
+
+* **Major updates** → Delayed by **30 days** (`semver-major-days: 30`)
+* **Minor updates** → Delayed by **7 days** (`semver-minor-days: 7`)
+* **Patch updates** → Delayed by **3 days** (`semver-patch-days: 3`)
+
+**Wildcard Matching:**
+
+* `"pandas*"` applies cooldown to all dependencies that start with `pandas`.
+* `"pandas"` in `exclude` ensures that only `"pandas"` (exact match) is excluded from cooldown.
+
+> [!NOTE]
+> To consider all dependencies for cooldown, you can:
+>
+> * Omit the `include` option which applies cooldown to all dependencies.
+> * Use `"*"` in `include` to apply cooldown to everything.
+>
+> Use **only** `exclude` setting if specific dependencies are to be excluded from cooldown.
+
+{% data reusables.dependabot.option-affects-security-updates %}