From 2709eb9107b8c19af8488ac71fa9f22d641b5c49 Mon Sep 17 00:00:00 2001
From: Rhys Arkins <rhys@arkins.net>
Date: Mon, 12 Feb 2018 07:00:55 +0100
Subject: [PATCH] docs: update docs/ files
Closes #1510
---
docs/branches-commits.md | 27 ++++
docs/configuration.md | 3 +-
docs/faq.md | 281 ---------------------------------------
docs/readme.md | 3 +
docs/status-checks.md | 18 ---
5 files changed, 31 insertions(+), 301 deletions(-)
create mode 100644 docs/branches-commits.md
create mode 100644 docs/readme.md
delete mode 100644 docs/status-checks.md
diff --git a/docs/branches-commits.md b/docs/branches-commits.md
new file mode 100644
index 0000000000..e1425a5334
--- /dev/null
+++ b/docs/branches-commits.md
@@ -0,0 +1,27 @@
+# Branches and Commits Methodology
+
+## Multiple files per branch
+
+Renovate can/should update multiple files in the same branch/PR. e.g. it might be `package.json` and `yarn.lock`, or it might be multiple `package.json` files in a monorepo.
+
+## One commit per branch
+
+To keep things neat from a user perspective, and simplify things from Renovate's perspective, we aim to always use just one commit per branch, even when multiple files need updating.
+
+A positive side effect of this is that it allows us to have a shortcut rule of, "If there's only one commit in the branch then it's clean, otherwise it must have been edited by users and we should stop updating it".
+
+## Updating branches
+
+If files in an already-existing branch need updating (e.g. an even newer version has been released), then we still aim to have just one commit. We achieve this in different ways per-platform.
+
+#### GitHub
+
+For GitHub, we use the low-level `git`-based API to manually make the commits and essentially "force push" to the existing branch without closing it. It's important to do this way because if you close a branch with a PR attached then the PR will be automatically closed by GitHub.
+
+#### GitLab
+
+In GitLab, Merge Request are not automatically closed if you delete the associated branch, so that gives us more flexibility. Therefore the way we update a branch is simply to delete it and then create the branch + commits again, and GitLab immediately reassociates the new (single) commit with the existing PR.
+
+#### VSTS
+
+VSTS is implemented similarly to GitLab.
diff --git a/docs/configuration.md b/docs/configuration.md
index a450794eef..831fdcdbf0 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -86,8 +86,7 @@ repository.
### package.json
If you add configuration options to your `package.json` then these will override
-any other settings above. Obviously, you can't set repository or package file
-location with this method.
+any other settings above.
```json
"renovate": {
diff --git a/docs/faq.md b/docs/faq.md
index cca0e6d1b8..4de37b3824 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -5,42 +5,12 @@ complicated - feel free to raise an
[Issue](https://github.com/renovateapp/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`.
-### Use an alternative branch for Pull Request target
-
-If for example your repository default branch is `master` but your Pull Requests
-should target branch `next`, then you can configure this via the `baseBranch`
-configuration option. To do this, add this line to the `renovate.json` in the
-_default_ branch (i.e. `master` in this example).
-
-```
-{
- "baseBranch": "next"
-}
-```
-
### Support private npm modules
If you are running your own Renovate instance, then the easiest way to support
@@ -68,254 +38,3 @@ or even specific packages at a different schedule.
If you want to control the days of the week or times of day that renovate
updates packages, use the `timezone` and `schedule` configuration options.
-
-By default, Renovate schedules will use the timezone of the machine that it's
-running on. This can be overridden in global config. Finally, it can be
-overridden on a per-repository basis too, e.g.:
-
-```
- "timezone": "America/Los_Angeles",
-```
-
-The timezone must be one of the valid
-[IANA time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
-
-Now that your timezone is set, you can define days of week or hours of the day
-in which renovate will make changes. For this we rely on text parsing of the
-library [later](http://bunkat.github.io/later/parsers.html#text) and its
-concepts of "days", "time_before", and "time_after".
-
-Example scheduling:
-
-```
-every weekend
-before 5:00am
-[after 10pm, before 5:00am]
-[after 10pm every weekday, before 5am every weekday]
-on friday and saturday
-```
-
-This scheduling feature can be particularly useful for "noisy" packages that are
-updated frequently, such as `aws-sdk`.
-
-To restrict `aws-sdk` to only weekly updates, you could add this package rule:
-
-```
- "packageRules": [
- {
- "packageNames": ["aws-sdk"],
- "schedule": ["after 9pm on sunday"]
- }
- ]
-```
-
-Note that schedule must be in the form of an array, even if only one schedule is
-present. Multiple entries in the array means "or".
-
-### 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 lock files (including sub-dependencies) up-to-date, even when `package.json` hasn't changed
-
-This is enabled by default, but its schedule is set to `['before 5am on monday']`. If you want it more frequently, then update the `schedule` field
-inside the `lockFileMaintenance` object.
-
-### 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 `packageRules` array to your configuration.
-2. Create one object inside this array
-3. Set field `packageNames` to value `["abc"]`
-4. Add the configuration option to the same object.
-
-e.g.
-
-```
-"packageRules": [
- {
- "packageNames": ["abc"],
- "assignees": ["importantreviewer"]
- }
-]
-```
-
-### Apply a rule, but only for packages starting with `abc`
-
-Do the same as above, but instead of using `packageNames`, use `packagePatterns`
-and a regex. e.g.
-
-```
-"packageRules": [
- {
- "packagePatterns": "^abc",
- "assignees": ["importantreviewer"]
- }
-]
-```
-
-### Group all packages starting with `abc` together in one PR
-
-As above, but apply a `groupName`, e.g.
-
-```
-"packageRules": [
- {
- "packagePatterns": "^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:
-
-```
-"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.
-
-### Separate patch releases from minor releases
-
-Renovate's default behaviour is to separate major and minor releases, while
-patch releases are also consider "minor". For example if you were running
-`q@0.8.7` you would receive one branch for the minor update to `q@0.9.7` and a
-second for the major update to `q@1.4.1`.
-
-If you set the configuration option `separatePatchReleases` to `true`, or you
-configure `automerge` to have value `"patch"`, then Renovate will then separate
-patch releases as well. For example, if you did this when running `q@0.8.7` then
-you'd receive three PRs - for `q@0.8.13`, `q@0.9.7` and `q@1.4.1`.
-
-Of course, most people don't want _more_ PRs, so you would probably want to
-utilise this feature to make less work for yourself instead. As an example, you
-might:
-
-* Update patch updates daily and automerge if they pass tests
-* Update minor and major updates weekly
-
-The result of this would hopefully be that you barely notice Renovate during the
-week while still getting the benefits of patch updates.
-
-### Update Meteor package.js files
-
-Renovate supports Meteor's `package.js` files - specifically, the `Npm.depends`
-section. As with npm, it will not renovate any `http*` URLs, but will keep all
-semantic versions up to date. (e.g. update version `1.1.0` to `1.1.1`)
-
-Meteor support is opt-in, meaning Renvoate won't attempt to search for Meteor
-files by default. To enable it, add `":meteor"` to your Renovate config
-`extends` array.
-
-e.g. if your renovate.json looks like:
-
-```json
-{
- "extends": [":library"]
-}
-```
-
-Then update it to be:
-
-```json
-{
- "extends": [":library", ":meteor"]
-}
-```
-
-Once you've done this, Renovate will:
-
-* Search the repository for all `package.js` files which include `Npm.depends`
-* Check the npm registry for newer versinos for each detected dependency
-* Patch the `package.js` file if updates are found and create an associated
- branch/PR
-
-If you wish to combine upgrades into one PR or any other similar configuration,
-you can do this just like with `package.json` dependencies by adding
-configuration or presets to your `renovate.json` file.
-
-### Update Dockerfile FROM dependencies
-
-Renovate supports updating `FROM` instructions in `Dockerfile`s.
-
-Dockerfile support is opt-in, meaning Renvoate won't attempt to search for
-Dockerfiles by default. To enable it, add `":docker"` to your Renovate config
-`extends` array.
-
-e.g. if your renovate.json looks like:
-
-```json
-{
- "extends": [":library"]
-}
-```
-
-Then update it to be:
-
-```json
-{
- "extends": [":library", ":docker"]
-}
-```
-
-Once you've done this, Renovate will:
-
-* Search the repository for all `Dockerfile` files that have `FROM x` as the
- first non-comment line
-* If x includes a digest, Renovate will check the Docker registry to see if a
- newer digest is available for the same tag and patch the Dockerfile
-* If x does not include a digest, Renovate will look up the current digest for
- this image/tag and add it to the Dockerfile
-
-If you wish to combine upgrades into one PR or any other similar configuration,
-you can do this just like with `package.json` dependencies by adding
-configuration or presets to your `renovate.json` file.
diff --git a/docs/readme.md b/docs/readme.md
new file mode 100644
index 0000000000..b237cf5b1b
--- /dev/null
+++ b/docs/readme.md
@@ -0,0 +1,3 @@
+# Renovate Developer Docs
+
+This directory is intended to provide documentation for developers/contributors on the Renovate project. For user-facing documentation - e.g. for how to confiure Renovate as a user - please see https://renovateapp.com/docs
diff --git a/docs/status-checks.md b/docs/status-checks.md
deleted file mode 100644
index 9e23bab92e..0000000000
--- a/docs/status-checks.md
+++ /dev/null
@@ -1,18 +0,0 @@
-# Status Checks
-
-## unpublish-safe
-
-Renovate includes a status showing whether upgrades are "unpublish-safe". This
-is because
-[packages less than 24 hours old may be unpublished by their authors](https://docs.npmjs.com/cli/unpublish).
-We recommend you wait for this status check to pass before merging unless the
-upgrade is urgent, otherwise you may find that packages simply disappear from
-the npm registry, breaking your build.
-
-If you would like to disable this status check, add `"unpublishSafe": false` to
-your config.
-
-If you would like to delay creation of Pull Requests until after this check
-passes, then add `"prCreation": "not-pending"` to your config. This way the PR
-will only be created once the upgrades in the branch are at least 24 hours old
-because Renovate sets the status check to "pending" in the meantime.
--
GitLab