[WIP] patcher concepts: what is a patch #2180
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
| @@ -1,3 +1,48 @@ | |||
| # What is a Patcher Patch? | |||
|
|
|||
| This page is under construction | |||
| A Patcher Patch is a set of instructions that Patcher can carry out to resolve a breaking change. | |||
There was a problem hiding this comment.
We can probably just call it a "Patch" rather than "Patcher Patch." Though we should clarify that patches work specifically with Patcher.
There was a problem hiding this comment.
A Patcher Patch is a set of instructions that Patcher can carry out to resolve a breaking change.
Can we be even more explicit? Something like:
A Patch is a set of instructions executed by Patcher that do code transformations. This is especially useful as a way to automate adoption of a breaking change with infrastructure as code, such as Terragrunt, OpenTofu, or Terraform.
| # etc | ||
| ``` | ||
|
|
||
| ## As a Consumer of Patches... |
There was a problem hiding this comment.
Could we reword to "For Module Consumers" and the section below to "For Module Authors"? In the end, anyone who writes patches will be the one who writes modules.
|
|
||
| ## As a Consumer of Patches... | ||
|
|
||
| All that's required to ingest patches for breaking IaC changes is to run a `patcher update` (with whatever flags you deem appropriate). |
There was a problem hiding this comment.
Can we set more context here? I'm assuming the user has no idea what Patcher is and is now reading this concepts section to understand it, so let's set the stage more.
For example:
As a module consumer, you make use of OpenTofu/Terraform modules to launch infrastructure by writing Terragrunt units (terragrunt.hcl files) or OpenTofu/Terraform code that calls a module.
It's a best practice to reference a specific version of an OpenTofu/Terraform module. But, over time, module authors release new versions of the module, and your consuming code slowly gets out of date. In some cases, the latest update of the underlying modules requires a breaking change to your code, meaning you can't just bump the version; you actually need to edit your consuming code to make use of the new version. That's when using a patch with Patcher comes in handy.
Patches can be consumed either by "push" -- when Patcher proactively opens a pull request with the latest update -- or a "pull" -- when you manually scan your repo to look at the current state of your infrastructure using the Patcher CLI tool.
Let's take a look at the experience of "pulling" available updates by using the Patcher CLI tool. The first step is to run patcher update...
Also, can you list an example of a full command the user would run, including the flags? This makes it more concrete for the user.
|
|
||
| All that's required to ingest patches for breaking IaC changes is to run a `patcher update` (with whatever flags you deem appropriate). | ||
|
|
||
| This command can be run locally, in which case, the steps outlined in the patch(es) would be executed within your codebase, and it would be up to you to apply IoC changes, or open them in a PR against your codebase, whichever is appropriate for your use case. |
There was a problem hiding this comment.
This sounds confusing as written. Can you more clearly separate the specific things that are happening?
For example:
patcher updateexecutes the steps in the patch- This changes the code in your local environment, but does not commit it or do any kind of
terragrunt applyor other operation against it. - It's up to you to apply the code and open a PR that submits it for review.
|
|
||
| This command can be run locally, in which case, the steps outlined in the patch(es) would be executed within your codebase, and it would be up to you to apply IoC changes, or open them in a PR against your codebase, whichever is appropriate for your use case. | ||
|
|
||
| Additionally, Gruntwork offers a GitHub Action to automate this process for you. |
There was a problem hiding this comment.
Use the "push" intro for this. Consider adding a header for pull and one for push.
|
|
||
| Additionally, Gruntwork offers a GitHub Action to automate this process for you. | ||
| Using the GitHub action, PRs will be opened against your codebase on a cadence specified by you, against environments, versions, etc. specified by you. | ||
| The intention with this GitHub action is to leave you, the repo owner, in full control of your upgrade cadence. |
There was a problem hiding this comment.
Include PR screenshot?
|
|
||
| ## As an Author of Patches... | ||
|
|
||
| As an author of a patch, this means that you are publishing a breaking change with a release of your module. |
There was a problem hiding this comment.
Switch to more active language. Instead of "this means that you are...," consider language like "Module authors periodically need to introduce breaking changes in their modules, causing a downstream painful experience for module consumers. With patches, module authors write not only the updated module code, but also include a patch YAML file that automatically updates consuming code to incorporate the breaking changes.
use patches to enable their modules consumers to automatically update consuming code to adopt breaking change.
There was a problem hiding this comment.
i like your verbage! incorporated 👍
as a general note, you'll likely notice i abstain from assertive/aggressive language. if i swung too far away from the docs site's conventions, please do feel free to call me out, always happy to fix it!
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
f780f50 to
d8ed77c
Compare
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
d8ed77c to
329c173
Compare
|
|
||
| Here is an example of what your PR will look like, after being generated by Patcher: | ||
|
|
||
| ** insert image of PR screenshot ** |
| The intention with this GitHub action is to leave the repo owner in full control of your upgrade cadence. | ||
|
|
||
| <details> | ||
| <summary>The example configuration is long. Click to expand!</summary> |
There was a problem hiding this comment.
This is a bit too casual IMO for our docs and doesn't match the style used elsewhere. How about just something very direct "GitHub Actions Workflow Example"
| When `patcher update` is run, the default mode is to click through the updates **interactively**. | ||
| In this mode, available updates are found, and the details of those updates are presented to you: | ||
|
|
||
| ** insert image here ** |
|
|
||
| You can choose to run in `--non-interactive` mode, which will modify the codebase and present results about what the program did at the end. | ||
|
|
||
| Interactively nor not, by default, a PR will _not_ be opened with the changes. |
There was a problem hiding this comment.
| Interactively nor not, by default, a PR will _not_ be opened with the changes. | |
| By default a PR will _not_ be opened with the changes. |
|
|
||
| ```bash | ||
| $ cd <repo-root-directory> | ||
| # give me ALL the patches for ALL the things |
There was a problem hiding this comment.
Again a bit too casual.
| # give me ALL the patches for ALL the things | |
| # Show what patches are available for everything in the current directory and all it's children |
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
329c173 to
2ff2cae
Compare
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
2ff2cae to
f295d9d
Compare
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
f295d9d to
28fb637
Compare
ceschae
force-pushed
the
ceschae/dev-650-patcher-conceptspatches
branch
from
28fb637 to
be1fbdf
Compare
| Using the GitHub action, PRs will be opened against your codebase on a cadence specified by you, against environments, versions, etc. specified by you. | ||
| The intention with this GitHub action is to leave the repo owner in full control of your upgrade cadence. | ||
|
|
||
| <details> |
There was a problem hiding this comment.
I worry this will go stale, and is also too much unexplained detail for a concept page. Maybe better to just remove it and link instead to the promotion workflows guides?
There was a problem hiding this comment.
just to confirm which noun we're talking about - remove "it" being the full example?
There was a problem hiding this comment.
Yep, the whole workflow file
|
|
||
| ```bash | ||
| # run 'update' non-interactively, only up to the next safe version, and publish a PR with the changes | ||
| $ patcher update --update-strategy next-safe --non-interactive --publish --pr-branch grunty/update-via-patcher --pr-title "[Patcher] Update All Dependencies to Next Safe" |
There was a problem hiding this comment.
This example references a handful of concepts the user probably isn't aware of yet. I'd suggest either removing the advanced concepts or linking to them explicitly (specifically the idea of update strategies, publishing PRs directly via patcher update)
There was a problem hiding this comment.
opting for a link instead of removing detail. i personally find that a complex example gets the gears turning for folks, and keeps them continuing to click through the docs. but i agree, providing a link to more docs is definitely needed, thank you!!
To-Dos