add(docs): merge.automerge_dependencies recipe and config docs (#610)

This change documents the newly released `merge.automerge_dependencies` configuration option.

docs/docs/config-reference.md

@@ -48,6 +48,54 @@ Require that the automerge label (`merge.automerge_label`) be set for Kodiak to
 
 When disabled, Kodiak will immediately attempt to merge any PR that passes all GitHub branch protection requirements.
 
+### `merge.automerge_dependencies.versions`
+
+- **type:** `string[]`
+- **options:** `"major"`, `"minor"`, `"patch"`
+- **default:** `[]`
+
+Kodiak will only automerge version upgrade types in this list. The author of the pull request must also be listed in [`merge.automerge_dependencies.usernames`](#mergeautomerge_dependenciesusernames).
+
+See ["Configuring automerge by upgrade type"](recipes.md##configuring-automerge-by-upgrade-type) for a full example.
+
+```toml
+# .kodiak.toml
+[merge.automerge_dependencies]
+# only auto merge "minor" and "patch" version upgrades.
+# do not automerge "major" version upgrades.
+versions = ["minor", "patch"]
+usernames = ["dependabot"]
+```
+
+Dependency upgrade types are parsed from the pull request title. The following table shows version upgrade examples:
+
+| title                           | upgrade |
+| ------------------------------- | ------- |
+| Bump lodash from 1.0.0 to 1.0.1 | patch   |
+| Bump lodash from 2.5.1 to 2.8.0 | minor   |
+| Bump lodash from 4.2.1 to 5.0.0 | major   |
+
+If Kodiak cannot determine the upgrade type from the pull request title, Kodiak will not automerge the pull request.
+
+See the [tests file](https://github.com/chdsbd/kodiak/blob/b1893ee6add4a1533bdac77999aad698e0b2e74c/bot/kodiak/test_dependencies.py#L10-L35) for more examples.
+
+### `merge.automerge_dependencies.usernames`
+
+- **type:** `string[]`
+- **default:** `[]`
+
+Kodiak will only automerge dependency upgrades for pull request authors in this list.
+
+See ["Configuring automerge by upgrade type"](recipes.md##configuring-automerge-by-upgrade-type) for a full example.
+
+```toml
+# .kodiak.toml
+[merge.automerge_dependencies]
+versions = ["minor", "patch"]
+# only automerge by upgrade version for pull requests authored by dependabot.
+usernames = ["dependabot"]
+```
+
 <span id="mergeblacklist_title_regex"/> <!-- handle old links -->
 
 ### `merge.blocking_title_regex`

docs/docs/recipes.md

@@ -19,7 +19,32 @@ require_automerge_label = false # default: true
 
 ## Automated dependency updates with Dependabot
 
-Kodiak can automerge Dependabot PRs without human intervention by configuring Dependabot to open pull requests with our [`merge.automerge_label`](/docs/config-reference#mergeautomerge_label) label.
+Kodiak can automerge all Dependabot PRs if you configure Dependabot to open pull requests with our [`merge.automerge_label`](/docs/config-reference#mergeautomerge_label) label.
+
+If you want to only merge specific upgrade types, like "major", "minor", "patch", you can configure [`merge.automerge_dependencies`](#configuring-automerge-by-upgrade-type).
+
+### Configuring automerge by upgrade type
+
+1. Install Kodiak following the [quick start guide](/docs/quickstart).
+2. Add `"dependabot"` and your automerge upgrade types to the `.kodiak.toml`
+
+> **NOTE:** Remove the `[bot]` suffix from GitHub Bot usernames. Instead of `"dependabot[bot]"` use `"dependabot"`.
+
+```toml
+# .kodiak.toml
+[merge]
+automerge_label = "ship it!"
+
+[merge.automerge_dependencies]
+# auto merge all PRs opened by "dependabot" that are "minor" or "patch" version upgrades. "major" version upgrades will be ignored.
+versions = ["minor", "patch"]
+usernames = ["dependabot"]
+
+# if using `update.always`, add dependabot to `update.ignore_usernames` to allow
+# dependabot to update and close stale dependency upgrades.
+[update]
+ignored_usernames = ["dependabot"]
+```
 
 ### Configuring Dependabot with the automerge label
 
@@ -62,7 +87,7 @@ version = 1
 # Instead of "dependabot[bot]" use "dependabot".
 auto_approve_usernames = ["dependabot"]
 
-# if using `update.always`, add dependabot to the blacklist to allow
+# if using `update.always`, add dependabot to `update.ignore_usernames` to allow
 # dependabot to update and close stale dependency upgrades.
 [update]
 ignored_usernames = ["dependabot"]