diff --git a/docs/usage/config-presets.md b/docs/usage/config-presets.md index ce255e710bf8b8da8a20ec47b9e6be24a78a7556..a843b186329c4326ae0b5a1a145aaa9009012a29 100644 --- a/docs/usage/config-presets.md +++ b/docs/usage/config-presets.md @@ -5,23 +5,23 @@ description: Renovate's support for ESLint-like shareable configs # Shareable Config Presets -This document describes how to configure your shared presets. +This page describes how to configure your shared presets. Read the [Key concepts, presets](./key-concepts/presets.md) page to learn more about presets in general. -Shareable config presets can only be used with the JSON format, other formats are not supported. +Shareable config presets must use the JSON or JSON5 formats, other formats are not supported. <!-- prettier-ignore --> !!! warning - `default.json` is intended for use with presets only! - Also, do not use a `renovate.json` file as a preset. + Only use `default.json` for your presets. <!-- prettier-ignore --> -!!! info - We've deprecated the use of a `renovate.json` file for presets as this can cause issues if the repository configuration uses a `renovate.json` file as well. +!!! warning + We've deprecated using a `renovate.json` file for presets, as this causes issues if the repository configuration _also_ uses a `renovate.json` file. + If you're using a `renovate.json` file to share your presets, rename it to `default.json`. <!-- prettier-ignore --> !!! tip - Describe what your preset is doing by using the `"description"` field. + Describe what your preset does in the `"description"` field. This way your configuration is self-documenting. ## Extending from a preset @@ -35,7 +35,8 @@ Presets should be hosted in repositories, which usually means the same platform <!-- prettier-ignore --> !!! warning - npm-based presets are deprecated and support will be removed in a future major release. + We deprecated npm-based presets. + We plan to drop the npm-based presets feature in a future major release of Renovate. You can set a Git tag (like a SemVer) to use a specific release of your shared config. @@ -46,10 +47,10 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | GitHub default | `github>abc/foo` | `default` | `https://github.com/abc/foo` | `default.json` | Default branch | | GitHub with preset name | `github>abc/foo:xyz` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | Default branch | | GitHub with preset name (JSON5) | `github>abc/foo:xyz.json5` | `xyz` | `https://github.com/abc/foo` | `xyz.json5` | Default branch | -| GitHub default with a tag | `github>abc/foo#1.5.4` | `default` | `https://github.com/abc/foo` | `default.json` | `1.5.4` | -| GitHub with preset name with a tag | `github>abc/foo:xyz#1.5.4` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | `1.5.4` | -| GitHub with preset name and path with a tag | `github>abc/foo//path/xyz#1.5.4` | `xyz` | `https://github.com/abc/foo` | `path/xyz.json` | `1.5.4` | -| GitHub with subpreset name and tag | `github>abc/foo:xyz/sub#1.5.4` | `sub` | `https://github.com/abc/foo` | `xyz.json` | `1.5.4` | +| GitHub default with a tag | `github>abc/foo#1.2.3` | `default` | `https://github.com/abc/foo` | `default.json` | `1.2.3` | +| GitHub with preset name with a tag | `github>abc/foo:xyz#1.2.3` | `xyz` | `https://github.com/abc/foo` | `xyz.json` | `1.2.3` | +| GitHub with preset name and path with a tag | `github>abc/foo//path/xyz#1.2.3` | `xyz` | `https://github.com/abc/foo` | `path/xyz.json` | `1.2.3` | +| GitHub with subpreset name and tag | `github>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.com/abc/foo` | `xyz.json` | `1.2.3` | ### GitLab @@ -58,10 +59,10 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | GitLab default | `gitlab>abc/foo` | `default` | `https://gitlab.com/abc/foo` | `default.json` | Default branch | | GitLab with preset name | `gitlab>abc/foo:xyz` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | Default branch | | GitLab with preset name (JSON5) | `gitlab>abc/foo:xyz.json5` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json5` | Default branch | -| GitLab default with a tag | `gitlab>abc/foo#1.5.4` | `default` | `https://gitlab.com/abc/foo` | `default.json` | `1.5.4` | -| GitLab with preset name with a tag | `gitlab>abc/foo:xyz#1.5.4` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.5.4` | -| GitLab with preset name and path with a tag | `gitlab>abc/foo//path/xyz#1.5.4` | `xyz` | `https://gitlab.com/abc/foo` | `path/xyz.json` | `1.5.4` | -| GitLab with subpreset name and tag | `gitlab>abc/foo:xyz/sub#1.5.4` | `sub` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.5.4` | +| GitLab default with a tag | `gitlab>abc/foo#1.2.3` | `default` | `https://gitlab.com/abc/foo` | `default.json` | `1.2.3` | +| GitLab with preset name with a tag | `gitlab>abc/foo:xyz#1.2.3` | `xyz` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.2.3` | +| GitLab with preset name and path with a tag | `gitlab>abc/foo//path/xyz#1.2.3` | `xyz` | `https://gitlab.com/abc/foo` | `path/xyz.json` | `1.2.3` | +| GitLab with subpreset name and tag | `gitlab>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitlab.com/abc/foo` | `xyz.json` | `1.2.3` | ### Gitea @@ -70,10 +71,10 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | Gitea default | `gitea>abc/foo` | `default` | `https://gitea.com/abc/foo` | `default.json` | Default branch | | Gitea with preset name | `gitea>abc/foo:xyz` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | Default branch | | Gitea with preset name (JSON5) | `gitea>abc/foo:xyz.json5` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json5` | Default branch | -| Gitea default with a tag | `gitea>abc/foo#1.5.4` | `default` | `https://gitea.com/abc/foo` | `default.json` | `1.5.4` | -| Gitea with preset name with a tag | `gitea>abc/foo:xyz#1.5.4` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | `1.5.4` | -| Gitea with preset name and path with a tag | `gitea>abc/foo//path/xyz#1.5.4` | `xyz` | `https://gitea.com/abc/foo` | `path/xyz.json` | `1.5.4` | -| Gitea with subpreset name and tag | `gitea>abc/foo:xyz/sub#1.5.4` | `sub` | `https://gitea.com/abc/foo` | `xyz.json` | `1.5.4` | +| Gitea default with a tag | `gitea>abc/foo#1.2.3` | `default` | `https://gitea.com/abc/foo` | `default.json` | `1.2.3` | +| Gitea with preset name with a tag | `gitea>abc/foo:xyz#1.2.3` | `xyz` | `https://gitea.com/abc/foo` | `xyz.json` | `1.2.3` | +| Gitea with preset name and path with a tag | `gitea>abc/foo//path/xyz#1.2.3` | `xyz` | `https://gitea.com/abc/foo` | `path/xyz.json` | `1.2.3` | +| Gitea with subpreset name and tag | `gitea>abc/foo:xyz/sub#1.2.3` | `sub` | `https://gitea.com/abc/foo` | `xyz.json` | `1.2.3` | ### Self-hosted Git @@ -82,10 +83,10 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c | Local default | `local>abc/foo` | `default` | `https://github.company.com/abc/foo` | `default.json` | Default branch | | Local with preset path | `local>abc/foo:xyz` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | Default branch | | Local with preset path (JSON5) | `local>abc/foo:xyz.json5` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json5` | Default branch | -| Local default with a tag | `local>abc/foo#1.5.4` | `default` | `https://github.company.com/abc/foo` | `default.json` | `1.5.4` | -| Local with preset name with a tag | `local>abc/foo:xyz#1.5.4` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | `1.5.4` | -| Local with preset name and path with a tag | `local>abc/foo//path/xyz#1.5.4` | `xyz` | `https://github.company.com/abc/foo` | `path/xyz.json` | `1.5.4` | -| Local with subpreset name and tag | `local>abc/foo:xyz/sub#1.5.4` | `sub` | `https://github.company.com/abc/foo` | `xyz.json` | `1.5.4` | +| Local default with a tag | `local>abc/foo#1.2.3` | `default` | `https://github.company.com/abc/foo` | `default.json` | `1.2.3` | +| Local with preset name with a tag | `local>abc/foo:xyz#1.2.3` | `xyz` | `https://github.company.com/abc/foo` | `xyz.json` | `1.2.3` | +| Local with preset name and path with a tag | `local>abc/foo//path/xyz#1.2.3` | `xyz` | `https://github.company.com/abc/foo` | `path/xyz.json` | `1.2.3` | +| Local with subpreset name and tag | `local>abc/foo:xyz/sub#1.2.3` | `sub` | `https://github.company.com/abc/foo` | `xyz.json` | `1.2.3` | <!-- prettier-ignore --> !!! tip @@ -95,21 +96,23 @@ You can set a Git tag (like a SemVer) to use a specific release of your shared c ## Example configs -An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing semver ranges". +An example of a small rule is `:preserveSemverRanges`, which has the description "Preserve (but continue to upgrade) any existing SemVer ranges.". It simply sets the configuration option `rangeStrategy` to `replace`. An example of a full config is `config:base`, which is Renovate's default configuration. -It mostly uses Renovate config defaults but adds a few smart customisations such as grouping monorepo packages together. +It mostly uses Renovate config defaults but adds a few smart customizations such as grouping monorepo packages together. <!-- prettier-ignore --> !!! note - The `:xyz` naming convention (with `:` prefix) is a special shorthand for the `default:` presets. - e.g. `:xyz` is equivalent to `default:xyz`. + The `:xyz` naming convention (with `:` prefix) is shorthand for the `default:` presets. + For example: `:xyz` is the same as `default:xyz`. ## How to Use Preset Configs -By default, the Renovate App's onboarding process will suggest `["config:base]"`. -If you are self hosting you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config. +By default, Renovate App's onboarding PR suggests the `["config:base]"` preset. +If you're self hosting, and want to use the `config:base` preset, then you must add `"onboardingConfig": { "extends": ["config:base"] }` to your bot's config. + +Read the [Full Config Presets](https://docs.renovatebot.com/presets-config/) page to learn more about our `config:` presets. A typical onboarding `renovate.json` looks like this: @@ -119,8 +122,10 @@ A typical onboarding `renovate.json` looks like this: } ``` -Say you want to modify the default behavior, for example scheduling Renovate to process upgrades during non-office hours only. -To do this you can modify the default `renovate.json` file like this: +Here's an example of using presets to change Renovate's behavior. +You're happy with the `config:base` preset, but want Renovate to create PRs when you're not at the office. +You look at our `schedule:` presets, and find the `schedule:nonOfficeHours` preset. +You put `schedule:nonOfficeHours` in the `extends` array of your `renovate.json` file, like this: ```json { @@ -128,9 +133,6 @@ To do this you can modify the default `renovate.json` file like this: } ``` -This makes use of the `schedules:` presets. -You can find the Renovate team's preset configs at the "Config Presets" section of [Renovate Docs](https://docs.renovatebot.com). - ## Preset Parameters If you browse the "default" presets, you will see some that have parameters, e.g.: @@ -170,18 +172,18 @@ To host your preset config on GitHub: - Add configuration files to this new repo for any presets you want to share. For the default preset, `default.json` will be checked. For named presets, `<preset-name>.json` will be loaded. For example, loading preset `library` would load `library.json`. No other files are necessary. - In other repos, reference it in an extends array like "github>owner/name", for example: -```json -{ - "extends": ["github>rarkins/renovate-config"] -} -``` + ```json + { + "extends": ["github>rarkins/renovate-config"] + } + ``` From then on Renovate will use the Renovate config from the preset repo's default branch. You do not need to add it as a devDependency or add any other files to the preset repo. ## GitLab-hosted Presets -For a private GitLab repository Renovate requires at least _Reporter_ level access. +For a private GitLab repository Renovate requires at least `Reporter` level access. To host your preset config on GitLab: