chore: update script to increment govcloud layer in docs (#3889)

Author: dreamorosi

.github/scripts/update_layer_arn.sh

@@ -1,10 +1,10 @@
 #!/bin/bash
 
-# This script is run during the reusable_update_v2_layer_arn_docs CI job,
+# This script is run during the publish_layer workflow,
 # and it is responsible for replacing the layer ARN in our documentation,
-# based on the output files generated by CDK when deploying to each pseudo_region.
+# based on the output files generated by CDK.
 #
-# see .github/workflows/reusable_deploy_v2_layer_stack.yml
+# see .github/workflows/publish_layer.yml
 
 set -eo pipefail
 
@@ -18,6 +18,7 @@ EOM
 fi
 
 CDK_OUTPUT_DIR=$1
+DOCS_FILE="docs/getting-started/lambda-layers.md"
 
 # Check if CDK output dir is a directory
 if [ ! -d "$CDK_OUTPUT_DIR" ]; then
@@ -44,7 +45,7 @@ for file in $files; do
     # Now replace the all "prefix"s in the file with the full new Layer ARN (line)
     # prefix:\d+ ==> line
     # sed doesn't support \d+ in a portable way, so we cheat with (:digit: :digit: *)
-    sed -i -e "s/$prefix:[[:digit:]][[:digit:]]*/$line/g" docs/index.md
+    sed -i -e "s/$prefix:[[:digit:]][[:digit:]]*/$line/g" $DOCS_FILE
 
     # We use the eu-central-1 layer as the version for all the frameworks (SAM, CDK, SLS, etc)
     # We could have used any other region. What's important is the version at the end.
@@ -65,8 +66,33 @@ for file in $files; do
 
         # Replace all the "prefix_pseudo_region"'s in the file
         # prefix_pseudo_region:\d+ ==> line_pseudo_region
-        sed -i -e "s/$prefix_pseudo_region:[[:digit:]][[:digit:]]*/$line_pseudo_region/g" docs/index.md
+        sed -i -e "s/$prefix_pseudo_region:[[:digit:]][[:digit:]]*/$line_pseudo_region/g" $DOCS_FILE
       done
     fi
   done
 done
+
+echo "[+] Finished processing all commercial regions"
+
+# Now we need to process GovCloud regions
+# 
+# GovCloud layers are not available in the CDK output files, but we know the ARN format and that the version is the same
+# as the one in eu-central-1. So we can optimistically update the version of the GovCloud layers in the documentation.
+#
+# The GovCloud ARNs are (note that the account IDs are different in both):
+# arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsTypeScriptV2:25
+# arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsTypeScriptV2:25
+
+version=$(echo "$line" | cut -d ':' -f 8) # version = 25
+arn_us_gov_west_1="arn:aws-us-gov:lambda:us-gov-west-1:165093116878:layer:AWSLambdaPowertoolsTypeScriptV2:$version"
+prefix_us_gov_west_1=$(echo "$arn_us_gov_west_1" | cut -d ':' -f 1-7)
+arn_us_gov_east_1="arn:aws-us-gov:lambda:us-gov-east-1:165087284144:layer:AWSLambdaPowertoolsTypeScriptV2:$version"
+prefix_us_gov_east_1=$(echo "$arn_us_gov_east_1" | cut -d ':' -f 1-7)
+echo -e "\t[*] ARN GovCloud US West 1: $arn_us_gov_west_1"
+echo -e "\t[*] ARN GovCloud US East 1: $arn_us_gov_east_1"
+# Replace all the "arn_us_gov_west_1"'s in the file
+sed -i -e "s/$prefix_us_gov_west_1:[[:digit:]][[:digit:]]*/$arn_us_gov_west_1/g" $DOCS_FILE
+# Replace all the "arn_us_gov_east_1"'s in the file
+sed -i -e "s/$prefix_us_gov_east_1:[[:digit:]][[:digit:]]*/$arn_us_gov_east_1/g" $DOCS_FILE
+echo "[+] Finished processing all GovCloud regions"
+echo "[+] Finished processing all regions"

.github/workflows/publish_layer.yml

@@ -110,7 +110,7 @@ jobs:
         id: create-pr
         uses: ./.github/actions/create-pr
         with: 
-          files: 'docs/index.md'
+          files: 'docs/getting-started/lambda-layers.md'
           temp_branch_prefix: 'ci-layer-docs'
           pull_request_title: 'chore(ci): update layer ARN on documentation'
           github_token: ${{ secrets.GITHUB_TOKEN }}

docs/maintainers.md

@@ -163,18 +163,22 @@ Some examples using our initial and new RFC templates: [#447](https://github.com
 
 ### Releasing a new version
 
-Firstly, make sure all the PRs that you want to include in the release are merged into the `main` branch.
-
-Next, run the integration tests one last time to make sure everything is working as expected. See [Run end to end tests](#run-end-to-end-tests) for more details.
-
-**Looks good, what's next?**
-
-Kickoff the `Make Release` workflow with the intended version - this might take around 20m-25m to complete.
+Releasing a new version is a multi-step process that requires up to 3 hours to complete. Below a checklist of the main steps to follow:
+
+1. **End to end tests**: Run the [e2e tests](#run-end-to-end-tests) and make sure they pass.
+2. **Version bump**: Run the `Make Version` workflow to bump the version. This will create a PR with the new version and a changelog. Visually inspect the diff and make sure the changelog and version are correct, then merge the PR.
+3. **Make Release**: Run the `Make Release` workflow. This will: 1/ run the unit tests again, 2/ build and publish to npmjs.com, 3/ build and deploy the Lambda layers to beta and prod, 4/ run canary tests, 5/ update the documentation with the new version.
+4. **Review and approve docs PR**: Once the `Make Release` workflow is complete, a PR will be created to update the documentation with the new version. Review and approve this PR **but do not merge it yet**. Take note of the Lambda layer version that was deployed, as this will be used in the next step.
+5. **Publish GovCloud Layers (Gamma)**: Run the `Layer Deployment (GovCloud)` workflow with the `main` branch, targeting the `gamma` account, and using the Lambda layer version from the previous step. This will publish the Lambda layers to GovCloud. Visually inspect the output JSON files and make sure the Lambda layer version and package version are correct.
+6. **Publish GovCloud Layers (Prod)**: Run the `Layer Deployment (GovCloud)` workflow with the `main` branch, targeting the `prod` account, and using the Lambda layer version from the previous step. This will publish the Lambda layers to GovCloud. Visually inspect the output JSON files and make sure the Lambda layer version and package version are correct.
+7. **Merge docs PR**: Once the `Layer Deployment (GovCloud)` workflow is complete, merge the PR to update the documentation with the new version.
+8. **Update SSM Parameters (Beta)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `beta` account, and using the package version from npm (i.e. `2.20.0`) and Lambda layer version from the previous steps. This will update the SSM parameters with the new version.
+9. **Verify SSM Parameters (Beta)**: Use the AWS CLI to verify that the SSM parameters were updated correctly. Run the following command: `aws ssm get-parameter --name=/aws/service/powertools/typescript/generic/all/latest` and `aws ssm get-parameter --name=/aws/service/powertools/typescript/generic/all/<version>` to verify that the SSM parameters were updated correctly.
+10. **Update SSM Parameters (Prod)**: Run the `SSM Parameters` workflow with the `main` branch, targeting the `prod` account, and using the package version from npm (i.e. `2.20.0`) and Lambda layer version from the previous steps. This will update the SSM parameters with the new version.
+11. **Update Docs**: Run the `Rebuild latest docs` workflow with the `main` branch using the package version from npm (i.e. `2.20.0`). This will update the documentation with the new version.
 
 Once complete, you can start drafting the release notes to let customers know **what changed and what's in it for them (a.k.a why they should care)**. We have guidelines in the release notes section so you know what good looks like.
 
-> **NOTE**: Documentation might take a few minutes to reflect the latest version due to caching and CDN invalidations.
-
 #### Release process visualized
 
 Every release makes dozens of checks, linting, canaries and deployments - all of these are automated through a number of distinct workflows that together make up the release process.
@@ -228,13 +232,25 @@ section Docs
     Create commit (Layer ARN)         : active, 10:18, 8s
     Open docs PR                      : active, 8s
 
-Review andmerge docs PR : milestone, m5
+Review and merge docs PR : milestone, m5
 
     Publish updated docs              : active, 2m
 
-Documentation release : milestone, m6
+section GovCloud
+    Publish GovCloud layers (Beta)    : active, 8s
+    Publish GovCloud layers (Prod)    : active, 8s
+GovCloud layers published : milestone, m6
+
+
+section Documentation
+Update SSM parameters (Beta)      : active, 8s
+Update SSM parameters (Prod)      : active, 8s
+
+SSM Parameters updated: milestone, m7
+
+Documentation release : milestone, m8
 
-Release complete : milestone, m7
+Release complete : milestone, m9
 ```
 
 #### Drafting release notes