Added Patcher overview page

_docs-sources/patcher/getting-started/index.md

@@ -0,0 +1,60 @@
+# Installing Patcher
+
+## Installation
+
+To install Patcher, download the appropriate package for your system from the [releases](https://github.com/gruntwork-io/patcher-cli/releases) page.
+
+### For MacOS and Linux users
+
+Patcher runs as a single binary called `patcher`. Make sure it's available within your `PATH`.
+
+1. After downloading Patcher, move it to your desired destination directory. If you're using MacOS, you will have to unzip the package. For other operating systems, the artifact you download is the executable itself.
+2. If necessary, rename the binary to `patcher`.
+```bash
+mv patcher_linux_amd64 patcher
+```
+3. Move `patcher` to a location available in your `PATH`. In the example below, we move to `/usr-local/bin`.
+```bash
+$ echo $PATH
+/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin:/Library/Apple/usr/bin:/Users/grunty/bin:/Users/grunty/go/bin
+$ mv patcher /usr/local/bin
+```
+
+## Before Running Patcher
+
+### GitHub Personal Access Token
+
+To fetch information from GitHub, Patcher requires a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), with the `repo` scope. Set the
+`GITHUB_OAUTH_TOKEN` environment variable to your GitHub Personal Access token:
+
+```bash
+export GITHUB_OAUTH_TOKEN="<YOUR_GITHUB_PAT>"
+```
+
+### Docker
+
+Starting in `0.4.1`, the Patcher update command applies patches using a Docker sandbox by default and will pull the latest version of the [`gruntwork/patcher_bash_env`](https://hub.docker.com/r/gruntwork/patcher_bash_env) image.
+
+To run the Patcher update command locally without Docker or in a CI pipeline you should add the `--skip-container-runtime` flag.
+
+## Running Patcher
+
+Patcher should be run in a local Terraform or Terragrunt Git repo. It will analyze _all_ modules that belong to the current folder including its children. Patcher supports `source` values only from GitHub.
+
+If you purchased and deployed our [Reference Architecture](https://gruntwork.io/reference-architecture/) and have your deployment organized in an `infrastructure-live` repository, we recommend running Patcher inside each environment folder, e.g. `infrastructure-live/dev`.
+
+### Patcher Report
+
+The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages.
+
+### Patcher Update
+
+The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders.
+
+## Debugging
+
+All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, run Patcher with the `--loglevel debug` flag.
+
+```
+patcher report --loglevel debug
+```

_docs-sources/patcher/index.md

@@ -1,60 +1,9 @@
-# Patcher
+# What is Gruntwork Patcher?
 
-## Installation
+Gruntwork Patcher helps you automatically keep your infrastructure code ([Terraform](https://www.terraform.io/) and [Terragrunt](https://terragrunt.gruntwork.io/)) up to date, including patching your code to make it work with backward incompatible module releases.
 
-To install Patcher, download the appropriate package for your system from the [releases](https://github.com/gruntwork-io/patcher-cli/releases) page.
+Without Patcher, the manual process of discovering updates and determining if they can be safely applied can take hours of an engineer's time for each module dependency.
 
-### For MacOS and Linux users
+You can use Patcher to maintain your dependencies on the Gruntwork Library which includes patches for recent breaking changes to Gruntwork modules. Patcher can also be used to update dependencies on your own modules and dependencies on open source modules using semantic versioning to decide which versions can be safely updated and which require manual intervention.
 
-Patcher runs as a single binary called `patcher`. Make sure it's available within your `PATH`.
-
-1. After downloading Patcher, move it to your desired destination directory. If you're using MacOS, you will have to unzip the package. For other operating systems, the artifact you download is the executable itself.
-2. If necessary, rename the binary to `patcher`.
-```bash
-mv patcher_linux_amd64 patcher
-```
-3. Move `patcher` to a location available in your `PATH`. In the example below, we move to `/usr-local/bin`.
-```bash
-$ echo $PATH
-/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin:/Library/Apple/usr/bin:/Users/grunty/bin:/Users/grunty/go/bin
-$ mv patcher /usr/local/bin
-```
-
-## Before Running Patcher
-
-### GitHub Personal Access Token
-
-To fetch information from GitHub, Patcher requires a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), with the `repo` scope. Set the
-`GITHUB_OAUTH_TOKEN` environment variable to your GitHub Personal Access token:
-
-```bash
-export GITHUB_OAUTH_TOKEN="<YOUR_GITHUB_PAT>"
-```
-
-### Docker
-
-Starting in `0.4.1`, the Patcher update command applies patches using a Docker sandbox by default and will pull the latest version of the [`gruntwork/patcher_bash_env`](https://hub.docker.com/r/gruntwork/patcher_bash_env) image.
-
-To run the Patcher update command locally without Docker or in a CI pipeline you should add the `--skip-container-runtime` flag.
-
-## Running Patcher
-
-Patcher should be run in a local Terraform or Terragrunt Git repo. It will analyze _all_ modules that belong to the current folder including its children. Patcher supports `source` values only from GitHub.
-
-If you purchased and deployed our [Reference Architecture](https://gruntwork.io/reference-architecture/) and have your deployment organized in an `infrastructure-live` repository, we recommend running Patcher inside each environment folder, e.g. `infrastructure-live/dev`.
-
-### Patcher Report
-
-The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages.
-
-### Patcher Update
-
-The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders.
-
-## Debugging
-
-All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, run Patcher with the `--loglevel debug` flag.
-
-```
-patcher report --loglevel debug
-```
+Gruntwork Patcher provides a straightforward README driven workflow for use when applying breaking changes that don't have patches. Patcher updates the dependency to the version with a breaking changes, generates a README file into the folder that contains the file that has been updated, and then stops. The README will contain the release note for the breaking change. The user reads the README file, takes any action that is required and then deletes the README file before running Patcher again.

_docs-sources/patcher/running-patcher/update.md

@@ -90,7 +90,7 @@ patcher update --non-interactive --skip-container-runtime prod
 
 ### Next Breaking
 
-Using the [next-breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module.
+Using the [next breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module.
 
 If Patcher updates a dependency to a breaking version, a `README-TO-COMPLETE-UPDATE.md` is written into the folder containing the dependendency. The `README-TO-COMPLETE-UPDATE.md` file contains a release note extract for each dependency in that folder that was updated to a breaking change.
 

docs/patcher/getting-started/index.md

@@ -0,0 +1,67 @@
+# Installing Patcher
+
+## Installation
+
+To install Patcher, download the appropriate package for your system from the [releases](https://github.com/gruntwork-io/patcher-cli/releases) page.
+
+### For MacOS and Linux users
+
+Patcher runs as a single binary called `patcher`. Make sure it's available within your `PATH`.
+
+1. After downloading Patcher, move it to your desired destination directory. If you're using MacOS, you will have to unzip the package. For other operating systems, the artifact you download is the executable itself.
+2. If necessary, rename the binary to `patcher`.
+```bash
+mv patcher_linux_amd64 patcher
+```
+3. Move `patcher` to a location available in your `PATH`. In the example below, we move to `/usr-local/bin`.
+```bash
+$ echo $PATH
+/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin:/Library/Apple/usr/bin:/Users/grunty/bin:/Users/grunty/go/bin
+$ mv patcher /usr/local/bin
+```
+
+## Before Running Patcher
+
+### GitHub Personal Access Token
+
+To fetch information from GitHub, Patcher requires a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), with the `repo` scope. Set the
+`GITHUB_OAUTH_TOKEN` environment variable to your GitHub Personal Access token:
+
+```bash
+export GITHUB_OAUTH_TOKEN="<YOUR_GITHUB_PAT>"
+```
+
+### Docker
+
+Starting in `0.4.1`, the Patcher update command applies patches using a Docker sandbox by default and will pull the latest version of the [`gruntwork/patcher_bash_env`](https://hub.docker.com/r/gruntwork/patcher_bash_env) image.
+
+To run the Patcher update command locally without Docker or in a CI pipeline you should add the `--skip-container-runtime` flag.
+
+## Running Patcher
+
+Patcher should be run in a local Terraform or Terragrunt Git repo. It will analyze _all_ modules that belong to the current folder including its children. Patcher supports `source` values only from GitHub.
+
+If you purchased and deployed our [Reference Architecture](https://gruntwork.io/reference-architecture/) and have your deployment organized in an `infrastructure-live` repository, we recommend running Patcher inside each environment folder, e.g. `infrastructure-live/dev`.
+
+### Patcher Report
+
+The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages.
+
+### Patcher Update
+
+The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders.
+
+## Debugging
+
+All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, run Patcher with the `--loglevel debug` flag.
+
+```
+patcher report --loglevel debug
+```
+
+<!-- ##DOCS-SOURCER-START
+{
+  "sourcePlugin": "local-copier",
+  "hash": "9ee56fd08f671b08f7486567a8757bd7"
+}
+##DOCS-SOURCER-END -->

docs/patcher/index.md

@@ -1,67 +1,17 @@
-# Patcher
+# What is Gruntwork Patcher?
 
-## Installation
+Gruntwork Patcher helps you automatically keep your infrastructure code ([Terraform](https://www.terraform.io/) and [Terragrunt](https://terragrunt.gruntwork.io/)) up to date, including patching your code to make it work with backward incompatible module releases.
 
-To install Patcher, download the appropriate package for your system from the [releases](https://github.com/gruntwork-io/patcher-cli/releases) page.
+Without Patcher, the manual process of discovering updates and determining if they can be safely applied can take hours of an engineer's time for each module dependency.
 
-### For MacOS and Linux users
+You can use Patcher to maintain your dependencies on the Gruntwork Library which includes patches for recent breaking changes to Gruntwork modules. Patcher can also be used to update dependencies on your own modules and dependencies on open source modules using semantic versioning to decide which versions can be safely updated and which require manual intervention.
 
-Patcher runs as a single binary called `patcher`. Make sure it's available within your `PATH`.
+Gruntwork Patcher provides a straightforward README driven workflow for use when applying breaking changes that don't have patches. Patcher updates the dependency to the version with a breaking changes, generates a README file into the folder that contains the file that has been updated, and then stops. The README will contain the release note for the breaking change. The user reads the README file, takes any action that is required and then deletes the README file before running Patcher again.
 
-1. After downloading Patcher, move it to your desired destination directory. If you're using MacOS, you will have to unzip the package. For other operating systems, the artifact you download is the executable itself.
-2. If necessary, rename the binary to `patcher`.
-```bash
-mv patcher_linux_amd64 patcher
-```
-3. Move `patcher` to a location available in your `PATH`. In the example below, we move to `/usr-local/bin`.
-```bash
-$ echo $PATH
-/opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/go/bin:/Library/Apple/usr/bin:/Users/grunty/bin:/Users/grunty/go/bin
-$ mv patcher /usr/local/bin
-```
-
-## Before Running Patcher
-
-### GitHub Personal Access Token
-
-To fetch information from GitHub, Patcher requires a [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token), with the `repo` scope. Set the
-`GITHUB_OAUTH_TOKEN` environment variable to your GitHub Personal Access token:
-
-```bash
-export GITHUB_OAUTH_TOKEN="<YOUR_GITHUB_PAT>"
-```
-
-### Docker
-
-Starting in `0.4.1`, the Patcher update command applies patches using a Docker sandbox by default and will pull the latest version of the [`gruntwork/patcher_bash_env`](https://hub.docker.com/r/gruntwork/patcher_bash_env) image.
-
-To run the Patcher update command locally without Docker or in a CI pipeline you should add the `--skip-container-runtime` flag.
-
-## Running Patcher
-
-Patcher should be run in a local Terraform or Terragrunt Git repo. It will analyze _all_ modules that belong to the current folder including its children. Patcher supports `source` values only from GitHub.
-
-If you purchased and deployed our [Reference Architecture](https://gruntwork.io/reference-architecture/) and have your deployment organized in an `infrastructure-live` repository, we recommend running Patcher inside each environment folder, e.g. `infrastructure-live/dev`.
-
-### Patcher Report
-
-The patcher [report command](/patcher/running-patcher/report) is a read-only version of Patcher that shows the changelog per module and its usages.
-
-### Patcher Update
-
-The patcher [update command](/patcher/running-patcher/update) allows you to update some or all of the module dependencies in the current folder and any child folders.
-
-## Debugging
-
-All logs are stored in the folder `~/.patcher/logs`. To also send `debug` logs, run Patcher with the `--loglevel debug` flag.
-
-```
-patcher report --loglevel debug
-```
 
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "7404617b36bd3d04bddebca633a30535"
+  "hash": "668d3f89f01f72d1ebb09fa5c9463714"
 }
 ##DOCS-SOURCER-END -->

docs/patcher/running-patcher/update.md

@@ -90,7 +90,7 @@ patcher update --non-interactive --skip-container-runtime prod
 
 ### Next Breaking
 
-Using the [next-breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module.
+Using the [next breaking update strategy](/patcher/update-strategies#next-breaking-update-strategy), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the version with the breaking change and stop. Otherwise, it will update the dependencies the latest version of that module.
 
 If Patcher updates a dependency to a breaking version, a `README-TO-COMPLETE-UPDATE.md` is written into the folder containing the dependendency. The `README-TO-COMPLETE-UPDATE.md` file contains a release note extract for each dependency in that folder that was updated to a breaking change.
 
@@ -145,6 +145,6 @@ Running Patcher again will complete the update to `5.1.1`, the `README-TO-COMPLE
 <!-- ##DOCS-SOURCER-START
 {
   "sourcePlugin": "local-copier",
-  "hash": "5c301767d0882df416aeeee2442f7776"
+  "hash": "82d2b541ef40b825238ca314baae000c"
 }
 ##DOCS-SOURCER-END -->

sidebars/patcher.js

@@ -1,23 +1,55 @@
 const sidebar = [
-    {
-      "label": "Patcher",
-      "type": "category",
-      "link": {
-        "type": "doc",
-        "id": "patcher/index"
+  {
+    label: "Gruntwork Patcher",
+    type: "category",
+    collapsible: false,
+    items: [
+      {
+        label: "Overview",
+        type: "category",
+        collapsible: false,
+        items: [
+          {
+            label: "What is Gruntwork Patcher?",
+            type: "doc",
+            id: "patcher/index"
+          },
+          {
+            label: "Update Strategies",
+            type: "doc",
+            id: "patcher/update-strategies"
+          },
+        ]
       },
-      "items": [
-        {
-          "Running Patcher": [
-            "patcher/running-patcher/report",
-            "patcher/running-patcher/update",
-            "patcher/running-patcher/upgrade"
-          ]
-        },
-        "patcher/telemetry",
-        "patcher/update-strategies"
-      ]
-    }
-  ]
-
-  module.exports = sidebar  
+      {
+        label: "Getting Started",
+        type: "category",
+        collapsible: false,
+        items: [
+          {
+            label: "Installing Patcher",
+            type: "doc",
+            id: "patcher/getting-started/index"
+          },
+          {
+            label: "Telemetry",
+            type: "doc",
+            id: "patcher/getting-started/telemetry"
+          }
+        ]
+      },
+      {
+        label: "Running Patcher",
+        type: "category",
+        collapsible: false,
+        items: [
+          "patcher/running-patcher/report",
+          "patcher/running-patcher/update",
+          "patcher/running-patcher/upgrade"
+        ]
+      }
+    ]
+  }
+]
+
+module.exports = sidebar