renovate/docs/design-decisions.md

# Design Decisions

This file documents the design choices as well as configuration options.

#### Stateless

No state is needed on `renovate` or GitHub side apart from what you see publicly in GitHub (branches, Pull Requests). It therefore doesn't matter if you stop/restart the script and would even still work if you had it running from two different locations, as long as their configuration was the same.

#### API only

We were really happy to discover that everything we needed to do could be achieved with the GitHub API. Therefore there's no messy `git` commands and essentially no risk of repository corruption.

## Synchronous Operation

The script current processes repositories, package files, and dependencies within them all synchronously.
- Greatly reduces chance of hitting GitHub API limits
- Implicitly enables any feature that results in multiple commits in the same branch
- Simplifies logging

Note: Initial queries to NPM are done in parallel.

## Multiple Configuration Methods

The script supports multiple [configuration methods](configuration.md) concurrently, and processed in order of priority.
This allows examples such as token configured via environment variable and labels configured via target `package.json`.

## Cascading Configuration

Configuration options applied per-package file override those per-repository, which override those which are global (all repositories).

The following options apply per-package file:

- Dependency Types
- Ignored Dependencies
- Labels
- Assignees
- Ignore Unstable
- Ignore Future
- Respect Latest
- Recreate Closed
- Recreate Unmergeable

The following options apply per-repository:

- Token

The following options apply globally:

- Log Level

## Automatic discovery of package.json locations

Default behaviour is to auto-discover all `package.json` locations in a repository and process them all.
Doing so means that "monorepos" are supported by default.
This can be overridden by the configuration option `packageFiles`, where you list the file paths manually (e.g. limit to just `package.json` in root of repository).

## Separate Branches per dependency

`renovate` will maintain separate branches per-dependency. So if 20 dependencies need updating, there will be at least 20 branches/PRs. Although this may seem undesirable, it was considered even less desirable if all 20 were in the same Pull Request and it's up to the users to determine which dependency upgrade(s) caused the build to fail.

However, it's still possible to override the default branch and PR name templates in such a way to produce a single branch for all dependencies. Here's an example configuration:

```javascript
templates: {
  branchName: 'renovate-all',
  prTitle: 'Renovate dependencies',
  prBody: 'This Pull Request is for package.json updates generated by the renovate utility.',
},
```

This could be done via configuration file or inside `package.json`. Perhaps it could be useful to make this a directly configurable option in future.

## One PR per Major release

`renovate` will create multiple branches/PRs if multiple major branch upgrades are available. For example if the current example is 1.6.0 and upgrades to 1.7.0 and 2.0.0 exist, then `renovate` will raise PRs for both the 1.x upgrade(s) and 2.x upgrade(s).

- It's often the case that projects can't upgrade major dependency versions immediately.
- It's also often the case that previous major versions continue receiving Minor or Patch updates.
- Projects should get Minor and Patch updates for their current Major release even if a new Major release exists

## Branch naming

Branches are named like `renovate/webpack-1.x` instead of `renovate/webpack-1.2.0`.

- Branches often receive updates (e.g. new patches) before they're merged.
- Naming the branch like `1.x` means its name still names sense if a `1.2.1` release happens

Note: Branch names are configurable using the `templates` field.

## Pull Request Recreation

By default, the script does not create a new PR if it finds an identical one already closed. This allows users to close unwelcome upgrade PRs and worry about them being recreated every run. Typically this is most useful for major upgrades.
This option is configurable.

The script does however close and create a replacement PR if the previous one was in an unmergeable state. It skips this though if additional edits have been made to the branch by someone else. This option is also configurable.

## Range handling

`renovate` always pins dependencies, instead of updating ranges. Even if the project is using tilde ranges, why not pin them for consistency if you're also using `renovate` every day?

Perhaps this will be made configurable in future once requirements are understood.

## Recreating Unmergeable Pull Requests

With the default behaviour of one branch per dependency, it's often that case that one PR has merge conflicts after an adjacent dependency update is merged. Although GitHub has added a web interface for simple merge conflicts, this is still annoying to resolve manually.

The default behaviour is that `renovate` will delete any unmergeable branches (which in turn closes the associated PR unmerged) and then recreate the branch and PR from the latest base commit. This means the same number of commits/builds as if you were resolving manually, however also means an increased number of Pull Requests because the old one gets closed and a new one created.

Note: `renovate` will only do this if the original branch hasn't been modified by anyone else. Also, this behaviour can be disabled via configuration.