docs: create maintenance guide (#249)

.github/MAINTENANCE.md

@@ -0,0 +1,56 @@
+# Maintenance Guide
+
+This document is intended for maintainers of this repository and outlines how to perform various maintenance-related activities, including descriptions of what processes are currently automated and which are not (yet).
+
+This repository contains extensive GitHub Actions [workflows](https://github.com/hashicorp/terraform-cdk-action/tree/main/.github/workflows) that automate as much of the project's lifecycle as possible. The project is built using [Projen](https://projen.io/) and as such **these workflows should not be edited directly**. Their sources can be found in the [`.projenrc/`](https://github.com/hashicorp/terraform-cdk-action/tree/main/projenrc) directory, and new workflows are added to the project in [`projenrc/index.ts`](https://github.com/hashicorp/terraform-cdk-action/blob/main/projenrc/index.ts).
+
+Note also that the GitHub Actions configuration file ([`action.yml`](https://github.com/hashicorp/terraform-cdk-action/blob/main/action.yml)) is generated by Projen and should similarly never be edited directly.
+
+
+## Security & Dependency Management
+
+Dependency upgrades (for security purposes as well as a best practice) can be divided into three categories: fully-automated, semi-automated, and not automated.
+
+### Fully Automated
+
+The following Actions exist to automate various dependency upgrades:
+
+- [upgrade-cdktf](https://github.com/hashicorp/terraform-cdk-action/actions/workflows/upgrade-cdktf.yml): This is a custom workflow (source [here](https://github.com/hashicorp/terraform-cdk-action/blob/main/projenrc/upgrade-cdktf.ts)) that runs four times a day and checks whether there is a new version of CDKTF itself, using the latest version published to npm as the source of truth. If a new version is found, it runs [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/update-cdktf.sh) script to update the CDKTF version in all the right places, as well as upgrading the minimum required (peer dependency) version of the `constructs` library, for which the source of truth is the peer dependency version of `constructs` required by the `cdktf` package. The PR that gets generated is auto-approved if it's a non-breaking change (i.e. a patch upgrade); if it's considered a breaking change (i.e. a major or minor upgrade), it requires a human engineer to approve it as a sanity-check, but aside from that the process is fully automated.
+- [upgrade-main](https://github.com/hashicorp/terraform-cdk-action/actions/workflows/upgrade-main.yml): This is a Projen built-in/default workflow that handles automated dependency updates. It currently runs on a weekly basis, which can be configured [here](https://github.com/hashicorp/terraform-cdk-action/blob/24cd9ba3eb91a58cd9e0cec5c443d4656dc93c89/projenrc/index.ts#L67). Projen will upgrade itself as part of this process. This process is 100% automated; as long as the build succeeds and any tests pass, the PR that is generated will be automatically merged without any human intervention.
+- [upgrade-terraform](https://github.com/hashicorp/terraform-cdk-action/actions/workflows/upgrade-terraform.yml): This is a custom workflow (source [here](https://github.com/hashicorp/terraform-cdk-action/blob/main/projenrc/upgrade-terraform.ts)) that runs once a week and checks whether there is a new version of Terraform; this check is done by [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/check-terraform-version.js) script using the HashiCorp [Releases API](https://api.releases.hashicorp.com/v1/releases/terraform/latest) as the source of truth. If a new version is found, it runs [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/update-terraform.sh) script to update the Terraform version in all the right places. The PR that gets generated is auto-approved if it's a non-breaking change (i.e. a patch upgrade); if it's considered a breaking change (i.e. a major or minor upgrade), it requires a human engineer to approve it as a sanity-check, but aside from that the process is fully automated.
+
+Dependabot is also [configured](https://github.com/hashicorp/terraform-cdk-action/blob/main/.github/dependabot.yml) to check for new security updates daily and, if found, make changes to the lockfile only. This is because Dependabot can sometimes address security issues in dependencies more quickly than Projen due to its atomic nature. While you could tweak the Dependabot settings, note that Projen and Dependabot do not generally play nicely together; in particular, Dependabot cannot make changes to `package.json` because Projen would just override these changes (hence the reason why Dependabot is currently limited to lockfile-only). If you wanted to fully automate dependency management using Dependabot, you would want to disable Projen's [automatic updates](https://projen.io/docs/api/typescript#projen.typescript.TypeScriptProjectOptions.property.depsUpgrade).
+
+### Semi-Automated
+
+The following Actions either need to be manually triggered or require significant manual effort as part of the upgrade process:
+
+- [upgrade-node](https://github.com/hashicorp/terraform-cdk-action/actions/workflows/upgrade-node.yml): This is a custom workflow (source [here](https://github.com/hashicorp/terraform-cdk-action/blob/main/projenrc/upgrade-node.ts)) that runs once a day to check if the current minimum version of Node.js supported by this project is less than 30 days away from EOL; this check is done by [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/check-node-versions.js) script using [this](https://nodejs.org/download/release/index.json) file as the source of truth. If the script determines that the current version is less than 30 days away from EOL, it runs [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/update-node.sh) script to upgrade the project to the next even-numbered (i.e. LTS-eligible) version of Node.js. This workflow generates a draft PR asking the user to check if the [`RunsUsing`](https://github.com/hashicorp/terraform-cdk-action/blob/8b74e0c471bd6eb9ea8869f1a73de83b7129717e/.projenrc.ts#L164) parameter of the Action should also be updated based on the possible options described [here](https://docs.github.com/en/actions/creating-actions/metadata-syntax-for-github-actions#runs-for-javascript-actions); GitHub Actions runners don't automatically support every LTS version - sometimes they skip one.
+  - There is also a [manual](https://github.com/hashicorp/terraform-cdk-action/actions/workflows/upgrade-node-manually.yml) version of this workflow in case we ever want/need to upgrade Node.js for reasons other than a version going LTS. This is nearly identical to the above workflow (and the source code is shared) except that it takes a Node.js version string as input, rather than using [this](https://github.com/hashicorp/terraform-cdk-action/blob/main/scripts/check-node-versions.js) script to determine what the new version should be.
+
+### Not Automated
+
+- **GitHub Actions version pinning**: Because this project leverages Projen, HashiCorp Security's [tsccr-helper](https://github.com/hashicorp/security-tsccr?tab=readme-ov-file#tsccr-helper-cli) CLI and other tooling cannot be used to manage/upgrade GitHub Actions versions. Instead, we have consolidated all of the versions into a single [object](https://github.com/hashicorp/terraform-cdk-action/blob/80228524bc07c2b48f2811051fb501adecf7f7d4/.projenrc.ts#L17-L29) in code that must be manually updated. Historically, one of the maintainers has followed these manual steps on a roughly monthly basis:
+  1. Look up the latest supported versions [here](https://github.com/hashicorp/security-tsccr/tree/main/components/github_actions)
+  2. Update the [object](https://github.com/hashicorp/terraform-cdk-action/blob/80228524bc07c2b48f2811051fb501adecf7f7d4/.projenrc.ts#L17-L29)
+  3. Run `npx projen`
+  4. Create a new PR with the title `chore(deps): update pinned versions of GitHub Actions`
+
+Also worth noting: Unlike many of our other Projen-based projects, this one does not have a workflow that upgrades JSII & TypeScript because this project does not use JSII at all. TypeScript is upgraded by the regular `upgrade-main` workflow described above.
+
+
+## Releasing
+
+Releases are fully automated by Projen. In general, this repository is [configured](https://github.com/hashicorp/terraform-cdk-action/blob/24cd9ba3eb91a58cd9e0cec5c443d4656dc93c89/projenrc/index.ts#L293-L297) to publish a new release only if any files under `dist/` or `action.yml` are changed; these are the only changes that are directly user-facing, so we don't publish releases for anything else in order to minimize churn. The new version number is automatically calculated by Projen using [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) and [Semantic Versioning](https://semver.org/).
+
+If you wanted to change the logic that governs when releases are triggered (such as running them on a schedule, or only for certain types of commits), see Projen's [documentation](https://projen.io/docs/publishing/releases-and-versioning) on this subject.
+
+### GitHub Actions Marketplace
+
+New versions of the Action are technically usable as soon as a new tag is published to GitHub; however, in order for the new version to show up on our [Marketplace](https://github.com/marketplace/actions/terraform-cdk-action) page, they must be manually published since GitHub unfortunately does not provide an API that can be used to automate Marketplace publishing. You can do this by going to the Edit Release page (URL format `https://github.com/hashicorp/terraform-cdk-action/releases/edit/v0.0.0`) and checking the box at the top:
+
+![Screenshot 2025-01-09 at 16 59 27](https://github.com/user-attachments/assets/1d0c79d1-1db8-4e2d-bcf2-27e687cfc80e)
+
+Don't forget to click the "Update release" button at the bottom of the page to save your changes. When you do, the new version is instantly posted to the Marketplace.
+
+As a next-best-thing solution to being able to publish to the Marketplace itself, we've [configured](https://github.com/hashicorp/terraform-cdk-action/blob/24cd9ba3eb91a58cd9e0cec5c443d4656dc93c89/projenrc/index.ts#L232-L266) a custom step that gets triggered after a successful release that posts a reminder in our `#feed-terraform-cdk-releases` channel reminding us to manually publish the new version to the Marketplace.