docs: improve design decisions development documentation (#7709)

Co-authored-by: Rhys Arkins <rhys@arkins.net>

docs/development/design-decisions.md

@@ -4,33 +4,46 @@ This file documents the design choices as well as configuration options.
 
 ## Stateless
 
-No state storage is needed on `renovate` or the source code repository apart from what you see publicly (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.
+A key feature of Renovate is that it does not require any state storage (e.g. on disk or in a database).
+Instead, Renovate's source of truth is the repository itself, e.g. branches, Issues and Pull Requests.
+Due to this design, it is possible to stop the script at any time without risking Renovate state being out of sync with repository state.
 
 ## Synchronous Operation
 
-The script current processes repositories and branches within them all synchronously.
+The script processes repositories and branches within them synchronously.
+This has the following benefits:
 
 - Greatly reduces the chance of hitting simultaneous API rate limits
 - Simplifies logging
 
 ## Cascading Configuration
 
-Configuration options applied per-package (e.g. with package rules) override those applied per package-type, which override those per-repository, which override those which are global (all repositories).
+We use a cascading configuration.
+This means that specific configuration options always override more general configuration options.
+
+From most specific to least specific:
+
+1. Update type (e.g. `major`, `minor`, `patch`)
+1. Package (e.g. `lodash`, `django`)
+1. Manager (e.g. `npm`, `pypi`)
+1. Repository config
+1. Global configuration
 
 ## Automatic discovery of package file locations
 
 The default behaviour is to auto-discover all package file (e.g. `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 `includePaths`, where you list the file paths manually (e.g. limit to just `package.json` in the root of the repository).
+
+This behaviour can be overridden by the configuration option `includePaths`, where you list the file paths manually.
+You could limit Renovate to only update the `package.json` in the root of the repository and ignore `package.json` files in other directories.
 
 ## Separate Branches per dependency
 
-By default, `renovate` will maintain separate branches per-dependency.
+By default, `renovate` will maintain separate branches for each 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.
+Although this may seem undesirable, it's even less desirable if all 20 were in the same Pull Request and it's very difficult to work out which upgrade caused the test failure.
 
-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.
+However, you can override the default branch and PR name templates to get a single branch for all dependencies.
 The `groupName` configuration option can be used at a repository level (e.g. give it the value `All`) and then all dependency updates will be in the same branch/PR.
 
 ## Separate Minor and Major PRs
@@ -38,31 +51,33 @@ The `groupName` configuration option can be used at a repository level (e.g. giv
 `renovate` will create multiple branches/PRs if both major and minor 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).
 
+Our reasons for separating minor and major PRs:
+
 - 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
 
-This can be overridden via the config option `separateMajorMinor`.
+This behaviour can be overridden via the config option `separateMajorMinor`.
 
 ## Branch naming
 
-Branches are named like `renovate/webpack-1.x` instead of `renovate/webpack-1.2.0`.
+Branches have names like `renovate/webpack-1.x` instead of `renovate/webpack-1.2.0`.
+
+We do this because:
 
 - 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 string templates.
+Note: You can configure the branch names by using the string template `branchName` and/or its sub-templates `branchPrefix` and `branchTopic`.
 
 ## Pull Request Recreation
 
-By default, the script does not create a new PR if it finds an identical one already closed.
+By default, the script does not create a new PR if it finds a previously-closed PR with the same branch name and PR title (assuming the PR title has a version in it).
 This allows users to close unwelcome upgrade PRs and not worry about them being recreated every run.
-Typically this is most useful for major upgrades.
-This option is configurable.
 
 ## Rebasing Unmergeable Pull Requests
 
-With the default behaviour of one branch per dependency, it's often that case that a PR gets merge conflicts after an adjacent dependency update is merged.
+With the default behaviour of one branch per dependency, it's often the case that a PR gets merge conflicts after an adjacent dependency update is merged.
 Although platforms often have a web interface for simple merge conflicts, this is still annoying to resolve manually.
 
 `renovate` will rebase any unmergeable branches and add the latest necessary commit on top of the most recent `master` commit.