Updated to Patcher v0.3.3 #926
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # Patcher Report | ||
|
|
||
| The `patcher report` command is a read-only version of Patcher that shows the changelog per module and its usages. | ||
|
|
||
| After scanning for dependencies, Patcher will show you the 'Modules View', similar to the screenshot below. | ||
|
|
||
|  | ||
|
|
||
| ### Navigation commands | ||
|
|
||
| 1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: | ||
|
|
||
|  | ||
|
|
||
| 2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. | ||
|
|
||
|  | ||
|
|
||
| :::info | ||
| Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. | ||
|
|
||
| ::: | ||
|
|
||
|  | ||
|
|
||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,106 @@ | ||
| # Patcher Update | ||
|
|
||
| The Patcher update command allows you to update some or all of the module dependencies in the current folder and any child folders. | ||
|
|
||
| The update command supports two modes: **interactive mode** and **non-interactive mode**. | ||
|
|
||
| ## Interactive Mode | ||
|
|
||
| In interactive mode, the update command lets you selectively update dependencies one module at time. | ||
|
|
||
| Example usage: | ||
| ``` | ||
| patcher update prod | ||
| ``` | ||
|
|
||
| After scanning for dependencies, Patcher will show you the 'Modules View'. | ||
|
|
||
| If all the dependencies are fully up to date, then Patcher shows a tick in the "Up to date" column. | ||
|
|
||
|  | ||
|
|
||
| If Patcher can update one or more usages of a module to a newer version, then Patcher offers two options: | ||
|
|
||
| * "Hit «ENTER» to update all usages to the next safe version." | ||
|
|
||
| * "Hit «b» to update all usages to the next version, even if it's a breaking change." | ||
|
|
||
|  | ||
|
|
||
| Pressing `ENTER` will update all the usages of that module to either the highest version before the next closest breaking change or the latest version of the dependecy, whichever is encountered first. | ||
|
|
||
| Pressing `b` will update all the usages of that module to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. | ||
|
|
||
| After updating the "Up to date" column is changed to show "Updated". This indicates that at least one of the dependencies on that module have been updated. | ||
|
|
||
|  | ||
|
|
||
| When you quit Patcher, it writes the details of all the updates to stdout in YAML format, for example: | ||
|
|
||
|  | ||
|
|
||
| ### Navigation commands | ||
|
|
||
| 1. While in the modules view, press `u` to see the usages. It shows all places where module is being used: | ||
|
|
||
|  | ||
|
|
||
| 2. While in the modules view, press `v` to see the changelogs from a module. Press `o` to open the page in the browser. | ||
|
|
||
|  | ||
|
|
||
| :::info | ||
| Some modules do not have a CHANGELOGS.md file. In this case, press `o` to open the releases page for that repository. | ||
|
|
||
| ::: | ||
|
|
||
|  | ||
|
|
||
| ## Non-Interactive Mode | ||
|
|
||
| In non-interactive mode, Patcher updates all module dependencies in the current folder (and child folders) according to the specified update strategy. | ||
|
|
||
| Non-interactive mode supports both the `next-safe` and `next-breaking` update strategies. | ||
|
|
||
| ### Next Safe (Default) | ||
|
|
||
| Using the [next safe update strategy](/patcher/update-strategies#next-safe-update-strategy-default), if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version **before** that breaking change. Otherwise, it will update the dependencies the latest version of that module. | ||
|
|
||
| Example usage: | ||
| ``` | ||
| patcher update --non-interactive --update-strategy next-safe | ||
| ``` | ||
| Or just | ||
| ``` | ||
| patcher update --non-interactive | ||
| ``` | ||
|
|
||
| ### 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. | ||
|
|
||
| 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. | ||
|
|
||
| Example usage: | ||
| ``` | ||
| patcher update --non-interactive --update-strategy next-breaking | ||
| ``` | ||
|
|
||
| ## Support for Third Party Modules | ||
|
|
||
| Starting in `0.3.3`, Patcher provides limited support for updating third party modules, this includes your own modules. The updates to third party module are limited to bumping the semver patch version. | ||
|
|
||
| Third party modules are supported in both interactive mode and non-interactive mode. | ||
|
|
||
| For example, the [terraform-aws-modules/terraform-aws-vpc](https://github.com/terraform-aws-modules/terraform-aws-vpc) module has two recent change: `4.0.2` and `5.0.0`. | ||
|
|
||
| And in `infrastructure-live/prod` there is a dependency on `terraform-aws-vpc/vpc`: | ||
| - `prod/us-east-1/prod/vpc/terragrunt.hcl` currently uses `4.0.0` | ||
|
|
||
| Patcher can update this dependency to `4.0.2` but because this only requires bumping the semver patch version. | ||
|
|
||
|  | ||
|
|
||
| Patcher cannot update from `4.0.x` to `5.0.0` and will instead show a `?` in the "Up to date" column and the message "Patcher can not determine an update plan for this dependency". | ||
|
|
||
|  |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,10 @@ | ||
| # Patcher Upgrade | ||
|
|
||
| ## CIS AWS v1.5 Upgrade | ||
|
|
||
| The `patcher upgrade cis` command is only available in `v0.1.x`. | ||
|
|
||
| This will upgrade your service catalogs to the latest module versions in the context of CIS v1.5. | ||
|
|
||
| For the CIS AWS Foundations Benchmark v1.5 upgrade, refer to [the upgrade guide](https://docs.gruntwork.io/guides/stay-up-to-date/cis/cis-1.5.0/). | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,26 @@ | ||
| # Telemetry | ||
|
|
||
| Patcher uses [sentry.io](https://sentry.io) for application performance monitoring and error tracking. This data helps us catch bugs quickly and improve Patcher. | ||
|
|
||
| ### Anonymous UUID | ||
|
|
||
| When you first run Patcher, we generate an anonymous UUID for that Patcher install. | ||
|
|
||
| This UUID is stored in `~/.patcher/config.json` and the same UUID will be sent each time you run Patcher. | ||
|
|
||
| Example `config.json` file: | ||
| ``` | ||
| // NOTE: Changing this file requires a restart of Patcher. | ||
| { | ||
| // Unique id used for correlating telemetry sent from this instance. | ||
| // Do not edit this value. | ||
| "telemetry-reporter-id": "a8884e6a-da99-43e3-86d0-f92a3605d731" | ||
| } | ||
| ``` | ||
|
|
||
| ### Opting Out | ||
|
|
||
| You can opt out of sending telemetry data by setting the `PATCHER_TELEMETRY_OPT_OUT` environment variable to `true`. | ||
| ```bash | ||
| export PATCHER_TELEMETRY_OPT_OUT=true | ||
| ``` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,97 @@ | ||||||
| # Update Strategies | ||||||
|
|
||||||
| Patcher supports two update strategies: **next safe** and **next breaking**. Theses update strategy determines how Patcher will behave if it encounters a breaking change that it cannot patch. | ||||||
|
|
||||||
| For example, the Gruntwork `terraform-aws-security/custom-iam-entity` module has two recent breaking changes: `0.62.0` and `0.65.0`. | ||||||
|
|
||||||
| And in `infrastructure-live/dev` there are 2 dependencies on `terraform-aws-security/custom-iam-entity`: | ||||||
| - `_global/ops-admin-role/terragrunt.hcl` currently uses `0.65.6` | ||||||
| - `_global/website-ci-cd-access/terragrunt.hcl` currently use `0.61.0` | ||||||
|
|
||||||
| ## "Next Safe" Update Strategy (Default) | ||||||
|
|
||||||
| The **next safe** strategy will update a dependency to either the highest version **before the next closest breaking change** or the latest version of the dependency, whichever is encountered first. | ||||||
|
|
||||||
| So if Patcher encounters a breaking change that it cannot patch then it will update the dependencies to the highest version before that breaking change and stop. Otherwise, if no breaking chnages are encountered it will update the dependencies the latest version of that module. | ||||||
|
|
||||||
| For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: | ||||||
| - `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version | ||||||
| - There are no breaking changes between `0.65.6` and `0.68.2` | ||||||
| - `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.61.1`, the highest version before `0.62.0` | ||||||
| - `0.62.0` is the next highest version that contains a breaking change which requires manual intervention | ||||||
|
|
||||||
| This is an example of the YAML that Patcher writes to `stdout` describing these updates: | ||||||
|
|
||||||
| ```yaml | ||||||
| successful_updates: | ||||||
| - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl | ||||||
| updated_modules: | ||||||
| - repo: terraform-aws-security | ||||||
| module: custom-iam-entity | ||||||
| previous_version: v0.65.6 | ||||||
| updated_version: v0.68.2 | ||||||
| - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl | ||||||
| updated_modules: | ||||||
| - repo: terraform-aws-security | ||||||
| module: custom-iam-entity | ||||||
| previous_version: v0.61.0 | ||||||
| updated_version: v0.61.1 | ||||||
| next_breaking_version: | ||||||
| version: v0.62.0 | ||||||
| release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 | ||||||
| ``` | ||||||
|
|
||||||
| ## "Next Breaking" Update Strategy | ||||||
|
|
||||||
| The **next breaking** strategy will update a dependency to either the next closest breaking change or the latest version of the dependency, whichever is encountered first. | ||||||
|
|
||||||
| So 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, if no breaking chnages are encountered it will update the dependencies the latest version of that module. | ||||||
|
|
||||||
| This may result in an update that requires manual intervention. If so, Patcher will provide additional information to help you understand what needs to be done. | ||||||
|
|
||||||
| Patcher does this by writing a `README-TO-COMPLETE-UPDATE.md` into the folder containing the dependendency. If more than one dependency in a folder has been update to a breaking version, then the `README-TO-COMPLETE-UPDATE.md` file will contain a release note extracts for each breaking change in that folder. | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| For example, for the dependencies on `terraform-aws-security/custom-iam-entity` in `infrastructure-live/dev`: | ||||||
| - `_global/ops-admin-role/terragrunt.hcl` will be updated from `0.65.6` to `0.68.2`, the latest version | ||||||
| - There are no breaking changes between `0.65.6` and `0.68.2` | ||||||
| - `_global/website-ci-cd-access/terragrunt.hcl` will be updated from `0.61.0` to `0.62.0`, the next highest version with a breaking change that requires manual intervention. | ||||||
|
|
||||||
| If any of the dependencies were updated to a breaking version, then the YAML that Patcher writes to `stdout` describing these updates will include a `manual_steps_you_must_follow` section listing the generated `README-TO-COMPLETE-UPDATE.md` files, for example: | ||||||
|
|
||||||
| ```yaml | ||||||
| successful_updates: | ||||||
| - file_path: ~/infrastructure-live/dev/_global/ops-admin-role/terragrunt.hcl | ||||||
| updated_modules: | ||||||
| - repo: terraform-aws-security | ||||||
| module: custom-iam-entity | ||||||
| previous_version: v0.65.6 | ||||||
| updated_version: v0.68.2 | ||||||
| - file_path: ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl | ||||||
| updated_modules: | ||||||
| - repo: terraform-aws-security | ||||||
| module: custom-iam-entity | ||||||
| previous_version: v0.61.0 | ||||||
| updated_version: v0.62.0 | ||||||
| next_breaking_version: | ||||||
| version: v0.62.0 | ||||||
| release_notes_url: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 | ||||||
| manual_steps_you_must_follow: | ||||||
| - instructions_file_path: ~/-infrastructure-live/dev/_global/website-ci-cd-access/README-TO-COMPLETE-UPDATE.md | ||||||
| ``` | ||||||
|
|
||||||
| This is the `README-TO-COMPLETE-UPDATE.md` written into `dev/_global/website-ci-cd-access`: | ||||||
|
|
||||||
| ```markdown | ||||||
| # custom-iam-entity v0.61.0 -> v0.62.0 (2023.06.05 12:26:30) | ||||||
|
|
||||||
| Updated dependency custom-iam-entity in ~/infrastructure-live/dev/_global/website-ci-cd-access/terragrunt.hcl to version v0.62.0, which contains breaking changes. You MUST follow the instructions in the release notes to complete this update safely: https://github.com/gruntwork-io/terraform-aws-security/releases/tag/v0.62.0 | ||||||
|
|
||||||
| Here are the release notes for version v0.62.0: | ||||||
|
|
||||||
|
|
||||||
| ## Description | ||||||
| **Terraform 1.1 upgrade**: We have verified that this repo is compatible with Terraform `1.1.x`! | ||||||
| - From this release onward, we will only be running tests with Terraform `1.1.x` against this repo, so we recommend updating to `1.1.x` soon! | ||||||
| - We have also updated the minimum required version of Terraform to `1.0.0`. While our repos might continue to be compatible with pre-1.0.0 version of Terraform, we are no longer making any guarantees of that. | ||||||
| - Once all Gruntwork repos have been upgraded to work with `1.1.x`, we will publish a migration guide with a version compatibility table and announce it all via the Gruntwork Newsletter. | ||||||
| ``` | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.