Wordsmith obnoxiously (#1694)

.changeset/.PREAMBLE.md

@@ -1,9 +1,9 @@
-skuba 9 is a reasonably large release, however we're hoping it won't be too much trouble to upgrade.
+skuba 9 is a reasonably large release but it shouldn't be too much trouble to upgrade.
 
 The main changes are:
 
-- ESLint 9 and flat config migration (in which `skuba format` should handle most of the work for you)
+- ESLint 9 and flat config migration (where `skuba format` should handle most of the work)
 - Swapping out `ts-node` for `tsx`
-- Some fixes in Docker & Buildkite files
+- Some fixes in Buildkite & Docker files
 
 Read the full changelog:

.changeset/big-weeks-enjoy.md

@@ -2,17 +2,25 @@
 'skuba': major
 ---
 
-lint: Migrate to ESLint 9 and `@typescript-eslint` 8.
+deps: ESLint 9 + `typescript-eslint` 8
 
-These changes may affect your project setup if customising your ESLint configuration. See the individual migration guides:
+This major upgrade bundles the following changes:
 
-- https://eslint.org/docs/latest/use/migrate-to-9.0.0
-- https://typescript-eslint.io/blog/announcing-typescript-eslint-v8
+- Migration to flat config format
 
-In addition, through these major upgrades, some lint rules have changed or have been renamed. You will likely need adjust your code after running ESLint.
+  `skuba format` will attempt to migrate your existing `.eslintignore` and `.eslintrc.js` files to a flat `eslint.config.js` file.
 
-Furthermore, `eslint-plugin-import` has been replaced with `eslint-plugin-import-x`. To migrate, any references to `eslint-plugin-import` should be replaced with `eslint-plugin-import-x`, and `import/` rules with `import-x/`.
+  See the [migration guide](https://eslint.org/docs/latest/use/configure/migration-guide) for more information.
 
-As part of this migration, skuba has migrated to using Flat ESLint configuration. Read the migration: https://eslint.org/docs/latest/use/configure/migration-guide.
+- Some lint rules have been changed or renamed
 
-`skuba format` will attempt to migrate to flat configuration for you, where `.eslintignore` and `.eslintrc` are replaced by `eslint.config.js`.
+  You will likely need to manually review and adjust your code after running `skuba lint`.
+
+- `eslint-plugin-import` has been replaced with `eslint-plugin-import-x`
+
+  To migrate, replace references to `eslint-plugin-import` with `eslint-plugin-import-x`, and `import/` rules with `import-x/`.
+
+Wider changes may be necessary if your project has a custom ESLint configuration. Refer to the following resources to get started:
+
+- [ESLint 9](https://eslint.org/docs/latest/use/migrate-to-9.0.0)
+- [`typescript-eslint` 8](https://typescript-eslint.io/blog/announcing-typescript-eslint-v8)

.changeset/dull-flowers-build.md

@@ -2,16 +2,13 @@
 'skuba': minor
 ---
 
-lint: Update Docker base images to point to AWS ECR Public and remove redundant `--platform` usage
+format, lint: Point Docker base images to AWS ECR Public and remove constant `--platform` arguments
 
-This updates references to `node:` or `python:` Docker images in your `Dockerfile` and `docker-compose.yml` files to point to AWS ECR Public to avoid Docker Hub rate limiting, along with removing redundant `--platform` [usage](https://docs.docker.com/reference/build-checks/from-platform-flag-const-disallowed/).
+This updates references to `node:` or `python:` Docker images in your Dockerfiles and `docker-compose.yml` files to point to AWS ECR Public to avoid Docker Hub rate limiting. It also removes [constant `--platform` arguments](https://docs.docker.com/reference/build-checks/from-platform-flag-const-disallowed/) from Dockerfiles.
 
-eg.
-
-```Dockerfile
-## Before
-FROM --platform=arm64 node:20-alpine AS dev-deps
-
-## After
-FROM public.ecr.aws/docker/library/node:20-alpine AS dev-deps
+```diff
+- FROM --platform=arm64 node:20-alpine AS dev-deps
++ FROM public.ecr.aws/docker/library/node:20-alpine AS dev-deps
 ```
+
+Your Dockerfiles may not be set up to build multi-platform images, so keep in mind that building them locally on an Intel x86 laptop may not yield images that can execute on AWS Graviton instances.

.changeset/empty-cherries-admire.md

@@ -4,11 +4,11 @@
 
 node, start: Replace `ts-node` with `tsx`
 
-`skuba start` and `skuba node` now use `tsx` instead of `ts-node` for running TypeScript files. `tsx` has better ESM interoperability, like support for dynamic imports (`await import()`), than `ts-node`.
+`skuba node` and `skuba start` now use `tsx` instead of `ts-node` to execute TypeScript files.
 
-There are some downsides for the REPL (which is what `skuba node` without any file is):
+`tsx` improves support for ESM features like dynamic [`import()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import)s. However, if you use its REPL by running `skuba node` without any arguments, there are a couple regressions to note:
 
-- `import` statements in the REPL are not supported; `require` and `await import()` are still supported.
-- Pasting code into the REPL may not work as well as `ts-node`. If encountering issues, a workaround could be to use [`.editor`](https://nodejs.org/en/learn/command-line/how-to-use-the-nodejs-repl#dot-commands)
+- Static [`import`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) declarations are no longer supported. Use `require` and `await import()` instead.
+- Pasting code into the editor may be more finicky by default. Consider using [`.editor`](https://nodejs.org/en/learn/command-line/how-to-use-the-nodejs-repl#dot-commands) mode.
 
-Otherwise, `skuba start` and `skuba node <file>` _should_ work as expected. However, it is difficult to comprehensively test every scenario, so this has been released as a major version. It is recommended to test your use-cases of `skuba start` and `skuba node` after upgrading.
+`skuba node <file>` and `skuba start` should continue to work as expected, but we have marked this as a major upgrade as it is difficult to comprehensively test every scenario. We strongly recommend to manually verify usage of `skuba node` and `skuba start` when you upgrade.

.changeset/heavy-scissors-divide.md

@@ -3,3 +3,5 @@
 ---
 
 template/koa-rest-api: Enable secure headers middleware by default
+
+See the [Koala documentation](https://github.com/seek-oss/koala/tree/be565a764ece9ec3802c2b6eeb3272cb77d1a695/src/secureHeaders) for more information.

.changeset/hot-crews-swim.md

@@ -2,4 +2,4 @@
 'skuba': minor
 ---
 
-lint: Removes obsolete version field from docker-compose.yml files
+format, lint: Remove obsolete `version` field from `docker-compose.yml` files

.changeset/hungry-keys-cover.md

@@ -2,4 +2,4 @@
 'skuba': patch
 ---
 
-template: Add required tags to `lambda-sqs-worker-cdk` template
+template/lambda-sqs-worker-cdk: Comply with AWS tagging guidance

.changeset/pink-seas-stare.md

@@ -2,4 +2,14 @@
 'skuba': minor
 ---
 
-template, format: Mount `.npmrc` files in `/tmp/` rather than `<workdir>/tmp/`, to avoid accidental inclusion in commits or published artifacts, as per the original intent of this handling.
+format, lint, template: Mount Buildkite `.npmrc` in `/tmp/` rather than `<workdir>/tmp/`
+
+This avoids accidental inclusion in Git commits or published artifacts, as per the original intent of this handling.
+
+```diff
+- secrets: id=npm,src=tmp/.npmrc
++ secrets: id=npm,src=/tmp/.npmrc
+
+- output-path: tmp/
++ output-path: /tmp/
+```

.changeset/rich-chairs-wink.md

@@ -2,19 +2,22 @@
 'skuba': minor
 ---
 
-lint: Replace `.buildkite/` files with duplicated YAML merge keys, for example:
+format, lint: Fix duplicated YAML merge keys in `.buildkite/` pipelines
 
-```yaml
-# Before
-- <<: *deploy
-  <<: *docker
-  label: stuff
-
-# After
-- <<: [*deploy, *docker]
-  label: stuff
+```diff
+- - <<: *deploy
+-   <<: *docker
++ - <<: [*deploy, *docker]
+    label: stuff
 ```
 
-This should have no functional change, and is to support standardised YAML parsing across different tools, including the latest ESLint upgrades.
+This change supports standardised YAML parsing across tools such as ESLint; it should not functionally alter the behaviour of your build pipeline.
+
+The bundled patch is fairly conservative and will not attempt to migrate more complex scenarios, such as where there are other keys between the merge keys. Take care with preserving the order of merge keys when manually updating other occurrences.
 
-This migration will not be capture all cases of this (e.g. if there are keys between the merge keys). If you have other cases, update them following the example above.
+```diff
+- - <<: *deploy
++ - <<: [*deploy, *docker]
+    label: stuff
+-   <<: *docker
+```

.changeset/shiny-parents-sit.md

@@ -1,5 +1,5 @@
 ---
-'skuba': minor
+'skuba': patch
 ---
 
 template/lambda-sqs-worker-cdk: Replace custom hooks with `@seek/aws-codedeploy-infra`

.changeset/strange-bats-doubt.md

@@ -2,8 +2,8 @@
 'skuba': minor
 ---
 
-lint, format: Remove [logic](https://github.com/seek-oss/skuba/pull/1226/) which skips autofixing Renovate branches when there is no open pull request.
+format, lint: Remove [logic](https://github.com/seek-oss/skuba/pull/1226) to skip autofixing Renovate branches when there is no open pull request
 
-Previously, this was put in place to prevent an issue where a Renovate branch can get stuck in the `Edited/Blocked` state without a pull request being raised.
+Previously, this was put in place to prevent an issue where a Renovate branch could get stuck in an `Edited/Blocked` state without a pull request being raised.
 
-Skuba's default autofix commits are [now ignored by skuba's recommended renovate configuration](https://github.com/seek-oss/rynovate/pull/121).
+skuba's default autofix commits are [now ignored](https://github.com/seek-oss/rynovate/pull/121) in our recommended Renovate configuration.

.changeset/thick-taxis-vanish.md

@@ -2,15 +2,23 @@
 'eslint-config-skuba': major
 ---
 
-Migrate to ESLint 9, `@typescript-eslint` 8, `eslint-config-seek` 14.
+ESLint 9 + `typescript-eslint` 8 + `eslint-config-seek` 14
 
-These changes may affect your project setup if customising your ESLint configuration. See the individual migration guides:
+This major upgrade bundles the following changes:
 
-- https://eslint.org/docs/latest/use/migrate-to-9.0.0
-- https://typescript-eslint.io/blog/announcing-typescript-eslint-v8
+- Migration to flat config format
 
-Through these major upgrades, some lint rules have changed or have been renamed. You will likely need to adjust your code after running ESLint.
+  See the [migration guide](https://eslint.org/docs/latest/use/configure/migration-guide) for more information.
 
-As part of this migration, this project has migrated to Flat ESLint configuration. Read the migration: https://eslint.org/docs/latest/use/configure/migration-guide.
+- Some lint rules have been changed or renamed
 
-Furthermore, `eslint-plugin-import` has been replaced with `eslint-plugin-import-x`. To migrate, any references to `eslint-plugin-import` should be replaced with `eslint-plugin-import-x`, and `import/` rules with `import-x/`.
+  You will likely need to manually review and adjust your code after running ESLint.
+
+- `eslint-plugin-import` has been replaced with `eslint-plugin-import-x`
+
+  To migrate, replace references to `eslint-plugin-import` with `eslint-plugin-import-x`, and `import/` rules with `import-x/`.
+
+Wider changes may be necessary if your project has a custom ESLint configuration. Refer to the following resources to get started:
+
+- [ESLint 9](https://eslint.org/docs/latest/use/migrate-to-9.0.0)
+- [`typescript-eslint` 8](https://typescript-eslint.io/blog/announcing-typescript-eslint-v8)

.changeset/twelve-bobcats-compete.md

@@ -2,4 +2,4 @@
 'skuba': patch
 ---
 
-template/\*: Update Docker base images to point to AWS ECR Public and remove redundant `--platform` usage
+template: Point Docker base images to AWS ECR Public and remove constant `--platform` arguments