Skip to content
Snippets Groups Projects
Unverified Commit 015a6b72 authored by HonkingGoose's avatar HonkingGoose Committed by GitHub
Browse files

docs(use cases): improve and simplify text (#13142)

parent ab3dc4e6
No related branches found
No related tags found
No related merge requests found
# Use Cases # Use Cases
This page describes some common use cases for Renovate, for those who are new and would like to get their heads around the capabilities. This page describes common use cases for Renovate, for those who are new and would like to get their heads around the capabilities.
## Development dependency updates ## Development dependency updates
The original use case, and still the most popular one, is for developers to automate dependency updating in their software projects. The original use case, and the most popular one, is for developers to automate dependency updating in their software projects.
### Updating of package files ### Updating of package files
The term "package file" is used to describe files which contain lists of dependencies, managed by a "package manager". The term "package file" is used to describe files which contain lists of dependencies, managed by a "package manager".
Example package files include `package.json` (managed by npm or Yarn), `Gemfile` (managed by Bundler), or `go.mod` (managed by `go` modules). Example package files include `package.json` (managed by npm or Yarn), `Gemfile` (managed by Bundler), or `go.mod` (managed by `go` modules).
Renovate will scan repositories to detect package files and their dependencies, look up if any newer versions exist, and then raise Pull Requests for available updates. Renovate scans repositories to detect package files and their dependencies, checks if any newer versions exist, and then raises Pull Requests for available updates.
The Pull Requests will patch the package files directly, and include Release Notes for the newer versions if they are available. The Pull Requests patch the package files directly, and include Release Notes for the newer versions (if they are available).
By default, there will be separate Pull Requests per dependency, and major updates will be separated out from non-major. By default, you'll get separate Pull Requests for each dependency, and major updates will be separated out from non-major.
### Package managers with lock files ### Package managers with lock files
Many package managers today support "lock files", which serve to freeze the entire dependency tree including transitive dependencies. Many package managers support "lock files", which "freeze" the entire dependency tree including transitive dependencies.
Such managers include npm, Yarn, Bundler, Composer, Poetry, Pipenv, and Cargo. npm, Yarn, Bundler, Composer, Poetry, Pipenv, and Cargo all support or use lock files.
When lock files exist, it's essential that any changes to package files are accompanied with a compatible change to the associated lock file. When lock files exist, changes to package files must come with a compatible change to the associated lock file.
Although Renovate can patch/update package files directly, a package manager's lock file is typically too complex to "reverse engineer" so therefore Renovate will rely on the package manager itself to perform the lock file update. Renovate can patch/update package files directly, but a lock file is too complex to "reverse engineer" so therefore Renovate lets the package manager itself do the lock file update.
Here is a simplified example: A simplified example:
- The repository has a `package.json` and `package-lock.json` containing version `1.0.0` of a dependency 1. The repository has a `package.json` and `package-lock.json` containing version `1.0.0` of a dependency
- Renovate determines that version `1.1.0` is available 1. Renovate sees that version `1.1.0` is available
- Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0` 1. Renovate patches the `package.json` to change the dependency's version from `1.0.0` to `1.1.0`
- Renovate then runs `npm install`, which triggers `npm` to update the `package-lock.json` accordingly 1. Renovate runs `npm install` to let `npm` update the `package-lock.json`
- Renovate then commits both the `package.json` and `package-lock.json` files together for the PR 1. Renovate commits the `package.json` and `package-lock.json`
1. Renovate creates the PR
### Custom dependency extraction ### Custom dependency extraction
Renovate supports 60+ different types of package files natively, but sometimes dependencies will not be detected by Renovate by default due to either: Renovate supports 60+ types of package files, but sometimes dependencies are not detected by Renovate by default due to either:
- The package manager/file format is not yet supported, or - The package manager/file format is not yet supported, or
- The file format is not a standard or is completely proprietary - The file format is not a standard or is proprietary
In such cases, Renovate has a "regex" manager which you can configure with custom patterns to extract dependencies regardless. In these cases you can use our "regex" manager to set your own custom patterns to extract dependencies.
Users can configure the regex manager by telling it: You can configure the regex manager by telling it:
- Which file pattern(s) to match - Which file pattern(s) to match
- How to identify the dependency name and version from within the file - How to identify the dependency name and version from within the file
- Which datasource (e.g. Docker registry, npm registry, etc) to use to look up new versions - Which datasource (e.g. Docker registry, npm registry, etc) to use to look up new versions
The end result is that Renovate can keep dependencies in custom file formats up-to-date as long as the dependency datasource is already known to Renovate. The end result is that Renovate can keep dependencies in custom file formats up-to-date as long as the dependency datasource is known to Renovate.
## DevOps tooling ## DevOps tooling
...@@ -85,7 +86,7 @@ An example from Renovate itself is the use of submodule updating to automate the ...@@ -85,7 +86,7 @@ An example from Renovate itself is the use of submodule updating to automate the
- Submodule updates are performed automatically whenever detected - Submodule updates are performed automatically whenever detected
- After the automatic update is merged, the documentation site is rebuilt and pushed live - After the automatic update is merged, the documentation site is rebuilt and pushed live
The above use case makes use of Renovate's "automerge" feature, which allows for fully automated updates without need for manual approval, merging, or even a PR at all if desired. The above use case makes use of Renovate's "automerge" feature, which allows for fully automated updates without needing manual approval, merging, or even a PR at all if desired.
Automerge is particularly useful for internal dependencies when it's best to use the approach of "if it passes tests then merge it". Automerge is particularly useful for internal dependencies when it's best to use the approach of "if it passes tests then merge it".
To learn more about "automerge" read the [key concepts, automerge](https://docs.renovatebot.com/key-concepts/automerge/) documentation. To learn more about "automerge" read the [key concepts, automerge](https://docs.renovatebot.com/key-concepts/automerge/) documentation.
...@@ -96,7 +97,7 @@ The below capabilities are common across the above use cases. ...@@ -96,7 +97,7 @@ The below capabilities are common across the above use cases.
### Batched updates ### Batched updates
Although Renovate defaults to separating each dependency update into its own PR, some users prefer to batch or "group" updates together. Renovate defaults to separating each dependency update into its own PR, but some users prefer to batch or "group" updates together.
For example, group all patch updates into one PR or even perhaps all non-major updates together (patches and minor updates). For example, group all patch updates into one PR or even perhaps all non-major updates together (patches and minor updates).
Renovate supports this capability using the `groupName` configuration as part of `packageRules`. Renovate supports this capability using the `groupName` configuration as part of `packageRules`.
...@@ -104,7 +105,7 @@ Renovate supports this capability using the `groupName` configuration as part of ...@@ -104,7 +105,7 @@ Renovate supports this capability using the `groupName` configuration as part of
### Scheduled updates ### Scheduled updates
Some users prefer to limit which hours of the day or week during which Renovate will raise updates. Some users prefer to limit which hours of the day or week during which Renovate will raise updates.
This may be to reduce "noise" during working hours, but also to reduce the chance of CI contention at times when developers are more likely to be waiting on tests to finish. This may be to reduce "noise" during working hours, but also to reduce the chance of CI contention at times when developers are likely to be waiting on tests to finish.
Renovate allows users to define time ranges during which to create updates using the `schedule` field. Renovate allows users to define time ranges during which to create updates using the `schedule` field.
...@@ -123,7 +124,7 @@ By having this dashboard concept it gives users both visibility and control over ...@@ -123,7 +124,7 @@ By having this dashboard concept it gives users both visibility and control over
### Configuration presets ### Configuration presets
It's pretty common that users will run Renovate on many repositories and want mostly similar config on them all too. It's common that users run Renovate on many repositories and therefore want a (mostly) similar config across their repositories.
Renovate supports the concept of configuration "presets" to avoid users needing to duplicate configuration across all such repos. Renovate supports the concept of configuration "presets" to avoid users needing to duplicate configuration across all such repos.
Configuration presets are JSON configuration files which are committed to repositories and then referenced from others. Configuration presets are JSON configuration files which are committed to repositories and then referenced from others.
...@@ -134,4 +135,4 @@ The typical workflow for a company is: ...@@ -134,4 +135,4 @@ The typical workflow for a company is:
- Create a dedicated repository to store the company's default Renovate settings - Create a dedicated repository to store the company's default Renovate settings
- Set that repository as the default `extends` value when onboarding new repositories - Set that repository as the default `extends` value when onboarding new repositories
This means that repositories get the centralized config by default, while any changes made to the centralized config repository are then propagated out to other repositories immediately. This means that repositories get the centralized config by default, and any changes made to the centralized config repository are propagated to other repositories immediately.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment