From 9be60b461f7932ecc295bc309dff9078ef08794b Mon Sep 17 00:00:00 2001
From: Rhys Arkins <rhys@keylocation.sg>
Date: Mon, 5 Jun 2017 23:00:01 +0200
Subject: [PATCH] Add configuration faq/guide (#270)
Closes #265
---
docs/faq.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++++
lib/index.js | 2 +
readme.md | 12 +++--
3 files changed, 133 insertions(+), 4 deletions(-)
create mode 100644 docs/faq.md
diff --git a/docs/faq.md b/docs/faq.md
new file mode 100644
index 0000000000..2a96531e48
--- /dev/null
+++ b/docs/faq.md
@@ -0,0 +1,123 @@
+# FAQ
+
+If you need a specific behaviour and it's not mentioned here - or it's more complicated - feel free to raise an [Issue](https://github.com/singapore/renovate/issues) - configuration questions are welcome in this repository.
+
+## What Is The Default Behaviour?
+
+Renovate will:
+
+- Look for configuration options in a `renovate.json` file and in each `package.json` file under the `renovate` object
+- Find and process all `package.json` files in each repository
+- Process `dependencies`, `devDependencies` and `optionalDependencies` in each `package.json`
+- Use separate branches/PR for each dependency
+- Use separate branches for each *major* version of each dependency
+- Pin dependencies to a single version, rather than use ranges
+- Update `yarn.lock` and/or `package-lock.json` files if found
+- Create Pull Requests immediately after branch creation
+
+## What If I Need To .. ?
+
+### Run renovate on all repositories that the account has access to
+
+Set configuration option `autodiscover` to `true`, via CLI, environment, or configuration file. Obviously it's too late to set it in any `renovate.json` or `package.json`.
+
+### Selectively enable or disable renovate for specific `package.json` files
+
+You could:
+
+- Add a `renovate.json` to the root of your repository and explicitly whitelist which `package.json` files you want renovated in the `packageFiles` configuration option, or
+- Add a `renovate` section to any `package.json` files you don't want renovated, with the configuration option `"enabled": false`
+
+### Disable renovate for certain dependency types
+
+If you want to disable `renovate` for `optionalDependencies`, for example, you could define your own `depTypes` array (in either a `renovate.json` or `package.json` file)
+
+### Use a single branch/PR for all dependency upgrades
+
+Add a configuration for configuration option `groupName` set to value `"all"`, at the top level of your `renovate.json` or `package.json`.
+
+### Use separate branches per dependency, but not one per major release
+
+Set configuration option `separateMajorReleases` to `false`.
+
+### Keep using semver ranges, instead of pinning dependencies
+
+Set configuration option `pinVersions` to `false`.
+
+### Keep `yarn.lock` sub-dependencies up-to-date, even when `package.json` hasn't changed
+
+Set configuration option `maintainYarnLock` to `true`.
+
+### Wait until tests have passed before creating the PR
+
+Set configuration option `prCreation` to `"status-success"`
+
+### Wait until tests have passed before creating a PR, but create the PR even if they fail
+
+Set configuration option `prCreation` to `"not-pending"`
+
+### Assign PRs to specific user(s)
+
+Set the configuration option `assignees` to an array of usernames.
+
+### Add labels to PRs
+
+Set the configuration option `labels` to an array of labels to use
+
+### Apply a rule, but only to package `abc`?
+
+1. Add a `packages` array to your configuration.
+2. Create one object inside this array
+3. Set field `packageName` to value `"abc"`
+4. Add the configuration option to the same object.
+
+e.g.
+
+```json
+"packages": [
+ {
+ "packageName": "abc",
+ "assignees": ["importantreviewer"]
+ }
+]
+```
+
+### Apply a rule, but only for packages starting with `abc`
+
+Do the same as above, but instead of using `packageName`, use `packagePattern` and a regex. e.g.
+
+```json
+"packages": [
+ {
+ "packagePattern": "^abc",
+ "assignees": ["importantreviewer"]
+ }
+]
+```
+
+### Group all packages starting with `abc` together in one PR
+
+As above, but apply a `groupName`, e.g.
+
+```json
+"packages": [
+ {
+ "packagePattern": "^abc",
+ "groupName": ["abc packages"]
+ }
+]
+```
+
+### Change the default branch name, commit message, PR title or PR description
+
+Set the `branchName`, `commitMessage`, `prTitle` or `prBody` configuration options:
+
+```json
+"branchName": "vroom/{{depName}}-{{newVersionMajor}}.x",
+"commitMessage": "Vroom vroom dependency {{depName}} to version {{newVersion}}",
+"prTitle": "Vroom {{depName}},
+```
+
+### Automatically merge passing Pull Requests
+
+Set configuration option `autoMerge` to `minor` if you want this to apply only to minor upgrades, or set to value `all` if you want it applied to both minor and major upgrades.
diff --git a/lib/index.js b/lib/index.js
index 5bc1228e7a..382f952758 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -102,6 +102,8 @@ async function configureRepository(config) {
delete defaultConfig.endpoint;
let prBody = `Welcome to [Renovate](https://keylocation.sg/our-tech/renovate)! Once you close this Pull Request, we will begin keeping your dependencies up-to-date via automated Pull Requests.
+The [Configuration](https://github.com/singapore/renovate/blob/master/docs/configuration.md) and [Configuration FAQ](https://github.com/singapore/renovate/blob/master/docs/faq.md) documents should be helpful.
+
#### Important!
You do not need to *merge* this Pull Request - renovate will begin even if it's closed *unmerged*.
diff --git a/readme.md b/readme.md
index cc3f374e1a..eff1863ee1 100644
--- a/readme.md
+++ b/readme.md
@@ -10,11 +10,11 @@
- Configurable via file, environment, CLI, and `package.json`
- Supports `yarn.lock` and `package-lock.json` files
- Supports GitHub and GitLab
-- Self-hosted
+- Open source and can be self-hosted
## GitHub App
-Renovate is now supported as a free GitHub app. Go to https://github.com/apps/renovate to enable it now.
+Renovate is now available as a free GitHub "App". Go to [https://github.com/apps/renovate](https://github.com/apps/renovate) to enable it now.
## Install
@@ -84,8 +84,12 @@ Note: The first time you run `renovate` on a repository, it will not upgrade any
## Deployment
-See [deployment docs](docs/deployment.md) for details.
+See [deployment docs](https://github.com/singapore/renovate/blob/master/docs/deployment.md) for details.
+
+## Configuration
+
+The [Configuration](https://github.com/singapore/renovate/blob/master/docs/configuration.md) and [Configuration FAQ](https://github.com/singapore/renovate/blob/master/docs/faq.md) documents should be helpful.
## Design Decisions
-See [design decisions doc](docs/design-decisions.md) for details.
+See [design decisions doc](https://github.com/singapore/renovate/blob/master/docs/design-decisions.md) for details.
--
GitLab