Add documentation for Patcher #763
Conversation
marinalimeira
requested review from
eak12913,
ebeneliason,
oredavids and
pete0emerson
as code owners
✅ Deploy Preview for pensive-meitner-faaeee ready!
To edit notification comments on pull requests, go to your Netlify site settings. |
|
|
||
| Patcher runs in single binary called `patcher`. Make sure it's available within your `PATH`. | ||
|
|
||
| 1. After downloading Patcher, unzip the package (only MacOS releases are zipped). Patcher runs in a single binary. |
There was a problem hiding this comment.
Patcher runs in a single binary
Do we need to add that context? I think it may be more clear to say something like:
Suggestion:
"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."
There was a problem hiding this comment.
Yes, that sounds good! Thanks
| ``` | ||
| mv patcher_linux_amd64 patcher | ||
| ``` | ||
| 3. Move `patcher` to a location available in your `PATH`. |
There was a problem hiding this comment.
Do we want the customer to do this? Or do we want them instead to install by placing the executable into some /opt/patcher location and then having some kind of symlink between /usr/local/bin and the patcher executable in /opt/patcher?
There was a problem hiding this comment.
Either would work. What would be the difference of moving to /opt/patcher?
|
|
||
| ## Before Running Patcher | ||
|
|
||
| To fetch information from GitHub, Patcher requires a GitHub Personal Access Token, with the `repo` scope. Set the |
There was a problem hiding this comment.
GitHub Personal Access Token
Consider linking this to GitHub's docs about PATs.
There was a problem hiding this comment.
Good point, would https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token be enough?
| 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. | ||
|
|
||
| In an `infrastructure-live` repository, we recommend running Patcher inside each environment folder, e.g. `infrastructure-live/dev`. |
There was a problem hiding this comment.
I think here we may want some added context about our Reference Architecture.
Something like:
"If you purchased and deployed our Reference Architecture and have your deployment organized in an infrastructure-live repository......"
|
|
||
| ### Patcher Report | ||
|
|
||
| In `0.2.x`, the only available command is `patcher report`. This is a read-only version of Patcher that shows the changelog per module and its usages. |
There was a problem hiding this comment.
| In `0.2.x`, the only available command is `patcher report`. This is a read-only version of Patcher that shows the changelog per module and its usages. | |
| In `v0.2.x`, the only available command is `patcher report`. This is a read-only version of Patcher that shows the changelog per module and its usages. |
There was a problem hiding this comment.
It may also be helpful to say something like:
"After running patcher report you will end up in the 'Modules View'".
This context will be helpful in your next 2 sections where you refer to other command that are available from the 'Modules View'
|
|
||
|  | ||
|
|
||
| 2.1. Some modules do not have a CHANGELOGS.md file.In this case, press `o` to open the releases page for that repository: |
There was a problem hiding this comment.
Should this be indented? Additionally, consider using an info call-out here rather than "2.1":
There was a problem hiding this comment.
Should this be indented?
Yes, I don't know how to fix this given the items below.
|
|
||
| ### CIS AWS v1.5 Upgrade | ||
|
|
||
| In `v0.1.x`, the only command available is `patcher upgrade cis`. This will upgrade your service catalogs to the latest |
There was a problem hiding this comment.
Did patcher upgrade cis get removed in v0.2.x? If it didn't, then your messaging above will need to be adjusted.
| ``` | ||
| 3. Move `patcher` to a location available in your `PATH`. | ||
| ```bash | ||
| echo $PATH |
There was a problem hiding this comment.
For examples where the second command is dependent on the output of the first, I find it useful to show the output of the first command. e.g.,
| echo $PATH | |
| echo $PATH | |
| > /usr/local/bin | |
| mv patcher /usr/local/bin |
There was a problem hiding this comment.
I will add an example of full path, hopefully this avoids confusion.
|
Thanks, Jason! For some context, see this slack thread. The docs are not in the right place, but given the docs website will have structural changes in the next couple of weeks, we will then move Patcher docs to the appropriate place. |
Jira: Patcher-115
Direct link for the preview: https://deploy-preview-763--pensive-meitner-faaeee.netlify.app/guides/stay-up-to-date/patcher