Create use cases page for Patcher

[brikis98]

This should have real-world examples of where Patcher is useful (see here for context). We could tell the Gruntwork story as one use case (i.e., maintain IaC Lib for hundreds of companies); we should definitely tell the internal maintainer story (e.g., util.jar, security.jar); we can tell the Terraform 0.12 upgrade story (painful backwards incompatible upgrade); we should tell a security focused story (talk about some vulnerability where you needed to do a backwards incompat change quickly to fix a huge security hole).

[ina-stoyanova]

Check out the DependaBot page in the web archive for inspiration on how they tell their story.

[ina-stoyanova]

We'll do this separately, as it needs more thinking than we had time. Moving it to patcher-v2

[brikis98]

I suspect this one will need to be done ASAP; otherwise, the landing page may be missing the "viable" in "minimal viable product." Without seeing concrete examples of what Patcher lets them do, I'm not sure many will have enough imagination to guess themselves, and sign up.

[infraredgirl]

Proposed text for use case 1. PTAL and suggest improvements, then I can incorporate them and write the rest of the use cases.

Use case 1: Update to Terraform 0.12 automatically

You can use Patcher to automatically update a codebase containing Terraform modules to a new Terraform version, including new major verions that contain backwards incompatible changes. Patcher will scan your codebase and open a pull request, such as the one shown in the screenshot below, that transforms your code to use the new version of Terraform. For example, Terraform 0.12 had a particularly painful backwards incompatible upgrade (details?), but Patcher can make such upgrades as painless and smooth as reviewing and merging a PR.

[infraredgirl]

Looksl like Jim was having trouble posting a comment here yesterday due to a GitHub outage, so I'll just post his comment here verbatim:

Thanks for getting started on this Ana! A few thoughts / reactions:

1. Having seen it written up, I think TF 0.12 is too old of a target. Let's change to "Update to Terraform 0.12 automatically" and include in the body of the text supports for each incremental step (e.g., 0.11 -> 0.12 -> 0.13 -> 0.14 -> 0.15 -> 1.0), including majorly backwards incompatible steps like 0.11 -> 0.12.
2. We have a bunch of "upgrade to terraform 12" PRs in almost every repo. Here's an example with a better diff you can use in the screenshot: https://github.com/gruntwork-io/terraform-aws-vpc/pull/66/files#diff-6158785a2e23bbb4ad88428f39e10ed47e8d672d14a8126f450e178c27fb9c4eR137-R164
3. I think somewhere, we should call out that Gruntwork has created patches to automatically do each of those upgrades. You can give an example of the steps the TF 0.13 -> 0.14 patch takes:
   1. Update required_version constraint in code.
   2. Replace version constraints in provider blocks with required_providers configuration.
   3. Update all the versions in source URLs to use the versions of Gruntwork modules that work with TF 0.14.
   4. Update CI / CD config to use TF 0.14.
   5. Update Terratest version to the version that supports TF 0.14.
   6. Run terraform fmt.
   7. Run terraform validate.
4. The PR screenshot could be one "tab" and the patch described above, formatted as a set of steps in YAML could be another tab (see the logs, metrics, and alarm "tabs" in the Heroku page for an example). Perhaps the patch tab has the title terraform-0.14.patch and the contents, just to give users the basic idea, might be YAML:

   code_transformations:
     # Set the required_version param in terraform { ... } blocks to 0.14
     - update_required_version_to_tf_0.14
     # Update all Gruntwork modules to versions that work with Terraform 0.14
     - update_module_versions
     # Update the CI build to use Terraform 0.14
     - update_ci_to_tf_0.14
     # Update Terratest to the version that works with Terraform 0.14
     - update_terratest_to_tf_0.14
   custom_scripts:
     # Replace version params in provider blocks with required_provider blocks
     - replace_provider_versions_with_required_providers
     # Run terraform fmt
     - terraform_fmt
     # Run terraform validate
     - terraform_validate

5. In terms of how to structure this content, I think the "zig zag" approach would work. So the "Upgrade to Terraform 1.0 automatically" could be on the left, with the screenshot of the 0.12 upgrade on the right; then some internal dependency story (e.g., util.jar) will be on the right, with a corresponding image on the left, and so on.

[infraredgirl]

Thanks for the input @brikis98! Next steps for me to work on:

• Incorporate Jim's comments into the text
• Create a "use cases" page: use the zig-zag structure; fill out the first use case
• Fill out the rest of the use cases