update(docs): documentation for blacklist_ option removal (#454)

Replace config options with there new alias. I was planning to document each option, but realized that could be confusing. Instead we indicate the former names as aliases and add some notes.
chdsbd · Jun 23, 2020 · 6864e26 · 6864e26
1 parent 7c68a71
commit 6864e26
Show file tree

Hide file tree

Showing 4 changed files with 34 additions and 16 deletions.
diff --git a/docs/docs/config-reference.md b/docs/docs/config-reference.md
@@ -42,37 +42,47 @@ 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.blacklist_title_regex`
+<span id="mergeblacklist_title_regex"/> <!-- handle old links -->
+
+### `merge.blocking_title_regex`
 
 - **type:** `string`
 - **default:** `"^WIP:.*"`
 - **options:** Regex pattern or `""`
+- **alias:** `merge.blacklist_title_regex`
 
 If a PR's title matches this regex, Kodiak will not merge the PR. This is useful
 to prevent merging work-in-progress PRs.
 
-Setting `merge.blacklist_title_regex = ""` disables this option.
+Setting `merge.blocking_title_regex = ""` disables this option.
 
 #### example
 
 ```
-merge.blacklist_title_regex = ".*DONT\s*MERGE.*"
+merge.blocking_title_regex = ".*DONT\s*MERGE.*"
 ```
 
-### `merge.blacklist_labels`
+> **NOTE:** `merge.blocking_title_regex` is a new name for `merge.blacklist_title_regex`. Both options behave identically.
+
+<span id="mergeblacklist_labels"/> <!-- handle old links -->
+
+### `merge.blocking_labels`
 
 - **type:** `string[]`
 - **default:** `[]`
 - **options:** List of label names
+- **alias:** `merge.blacklist_labels`
 
 Kodiak will not merge a PR with any of these labels.
 
 #### example
 
 ```
-merge.blacklist_labels = ["wip"]
+merge.blocking_labels = ["wip"]
 ```
 
+> **NOTE:** `merge.blocking_labels` is a new name for `merge.blacklist_labels`. Both options behave identically.
+
 ### `merge.method`
 
 - **type:** `string`
@@ -299,12 +309,15 @@ When disable, Kodiak will update any PR.
 
 This option only applies when `update.always = true`.
 
-### `update.blacklist_usernames`
+<span id="updateblacklist_usernames"/> <!-- handle old links -->
+
+### `update.ignored_usernames`
 
 - **type:** `string[]`
 - **default:** `[]`
+- **alias:** `update.blacklist_usernames`
 
-When `update.always` is enabled, pull requests opened by a user with a username in the `update.blacklist_usernames` list will be ignored for updates. However, when merging the PR, Kodiak will still update the PR if required by GitHub Branch Protection to merge the pull request.
+When `update.always` is enabled, pull requests opened by a user with a username in the `update.ignored_usernames` list will be ignored for updates. However, when merging the PR, Kodiak will still update the PR if required by GitHub Branch Protection to merge the pull request.
 
 If the user is a bot user, remove the `[bot]` suffix from their username. So instead of `dependabot-preview[bot]`, use `dependabot-preview`.
 
@@ -313,9 +326,11 @@ This setting has no effect when `update.always` is disabled.
 #### example
 
 ```
-update.blacklist_usernames = ["bernard-lowe", "dependabot-preview"]
+update.ignored_usernames = ["bernard-lowe", "dependabot-preview"]
 ```
 
+> **NOTE:** `update.ignored_usernames` is a new name for `update.blacklist_usernames`. Both options behave identically.
+
 ### `approve.auto_approve_usernames`
 
 - **type:** `string[]`
@@ -372,11 +387,11 @@ require_automerge_label = true
 # If a PR's title matches this regex, Kodiak will not merge the PR. This is
 # useful to prevent merging work-in-progress PRs.
 #
-# Setting `merge.blacklist_title_regex = ""` disables this option.
-blacklist_title_regex = "" # default: "^WIP:.*", options: "" (disables regex), a regex string (e.g. ".*DONT\s*MERGE.*")
+# Setting `merge.blocking_title_regex = ""` disables this option.
+blocking_title_regex = "" # default: "^WIP:.*", options: "" (disables regex), a regex string (e.g. ".*DONT\s*MERGE.*")
 
 # Kodiak will not merge a PR with any of these labels.
-blacklist_labels = [] # default: [], options: list of label names (e.g. ["wip"])
+blocking_labels = [] # default: [], options: list of label names (e.g. ["wip"])
 
 # Choose merge method for Kodiak to use.
 #

diff --git a/docs/docs/features.md b/docs/docs/features.md
@@ -30,7 +30,7 @@ When merging a pull request, Kodiak will update the PR if out of date with the t
 
 To have Kodiak immediately update any PR that is out-of-date, enable [`update.always`](config-reference.md#updatealways).
 
-If you use Kodiak with a dependancy update bot, you should disable auto updates for the bot via [`update.blacklist_usernames`](config-reference.md#updateblacklist_usernames). See [Automated dependency updates with Dependabot](recipes.md#automated-dependency-updates-with-dependabot) for more information.
+If you use Kodiak with a dependancy update bot, you should disable auto updates for the bot via [`update.ignored_usernames`](config-reference.md#updateignored_usernames). See [Automated dependency updates with Dependabot](recipes.md#automated-dependency-updates-with-dependabot) for more information.
 
 ## Merging Pull Requests
 
@@ -64,8 +64,8 @@ With GitHub Branch Protection, required status checks will prevent a pull reques
 
 Kodiak has some internal features to disable merging as well:
 
-- [`merge.blacklist_title_regex`](config-reference.md#mergeblacklist_title_regex) – disable Kodiak merging based on a regex matching to the pull request title
-- [`merge.blacklist_labels`](config-reference.md#mergeblacklist_labels) – disable Kodiak merging based on labels applied to the PR
+- [`merge.blocking_title_regex`](config-reference.md#mergeblocking_title_regex) – disable Kodiak merging based on a regex matching to the pull request title
+- [`merge.blocking_labels`](config-reference.md#mergeblocking_labels) – disable Kodiak merging based on labels applied to the PR
 - [`merge.do_not_merge`](config-reference.md#mergedo_not_merge) – completely disable Kodiak from merging any PR. This is useful if you only want to use Kodiak for updating pull requests.
 
 ### Efficient Merging

diff --git a/docs/docs/recipes.md b/docs/docs/recipes.md
@@ -65,10 +65,10 @@ auto_approve_usernames = ["dependabot"]
 # if using `update.always`, add dependabot to the blacklist to allow
 # dependabot to update and close stale dependency upgrades.
 [update]
-blacklist_usernames = ["dependabot"]
+ignored_usernames = ["dependabot"]
 ```
 
-If you use Kodiak with [`update.always`](/docs/config-reference#updatealways) enabled, add Dependabot to the [`update.blacklist_usernames`](/docs/config-reference#updateblacklist_usernames) list. If a PR by Dependabot is updated by another user, Dependabot will not update or close the PR when stale. This setting prevents Kodiak from breaking Dependabot PRs.
+If you use Kodiak with [`update.always`](/docs/config-reference#updatealways) enabled, add Dependabot to the [`update.ignored_usernames`](/docs/config-reference#updateignored_usernames) list. If a PR by Dependabot is updated by another user, Dependabot will not update or close the PR when stale. This setting prevents Kodiak from breaking Dependabot PRs.
 
 ## The Favourite
 

diff --git a/kodiak.code-workspace b/kodiak.code-workspace
@@ -8,6 +8,9 @@
     },
     {
       "path": "web_api"
+    },
+     {
+      "path": "docs"
     },
     {
       "path": "infrastructure"