Uplift template READMEs (#334)

Co-authored-by: Toby Heighway <[email protected]>

.changeset/young-terms-sleep.md

@@ -0,0 +1,5 @@
+---
+'skuba': patch
+---
+
+**template:** Uplift READMEs

README.md

@@ -187,7 +187,7 @@ This initialises a new directory and Git repository.
 [aws lambda]: https://tech-strategy.ssod.skinfra.xyz/docs/v1/technology.html#lambda
 [koa]: https://koajs.com/
 [resource api]: https://tech-strategy.ssod.skinfra.xyz/docs/v1/components.html#resource-api
-[seek-jobs]: https://github.com/SEEK-Jobs
+[seek-jobs]: https://github.com/orgs/seek-jobs/sso
 [seek-oss]: https://github.com/seek-oss
 [semantic-release]: https://github.com/semantic-release/semantic-release/
 [serverless]: https://serverless.com/

template/express-rest-api/README.md

@@ -2,20 +2,51 @@
 
 [![Powered by skuba](https://img.shields.io/badge/🤿%20skuba-powered-009DC4)](https://github.com/seek-oss/skuba)
 
+Next steps:
+
+1. [ ] Finish templating if this was skipped earlier:
+
+   ```shell
+   yarn skuba configure
+   ```
+
+2. [ ] Create a new repository in the appropriate GitHub organisation.
+3. [ ] Add the repository to BuildAgency;
+       see [Builds at SEEK] for more information.
+4. [ ] Fill out [.me](.me) to power SEEK's system catalogue;
+       see the [Codex] documentation for more information.
+5. [ ] Add Datadog configuration and data classification tags to [.gantry/common.yml](.gantry/common.yml);
+       see the [Gantry] documentation for more information.
+6. [ ] Push local commits to the upstream GitHub branch.
+7. [ ] Delete this checklist 😌.
+
 ## Table of contents
 
 - [Design](#design)
 - [Development](#development)
   - [Test](#test)
   - [Lint](#lint)
+  - [Start](#start)
   - [Deploy](#deploy)
 - [Support](#support)
   - [Dev](#dev)
   - [Prod](#prod)
 
 ## Design
 
-TODO: explain the design of your API here.
+<%-repoName %> is a Node.js HTTP server built in line with our [technology strategy].
+It uses the [Express] middleware framework and common SEEK packages.
+Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.
+
+This project is deployed as a containerised application with [Gantry].
+A typical resource API instance does not require more than 1 vCPU,
+so we eschew clustering configurations in favour of a single Node.js process per container.
+Under load, we autoscale horizontally in terms of container count up to `autoScaling.maxCount`.
+
+Gantry configures [CodeDeploy] for a blue-green deployment approach.
+A smoke test is run against the new version before traffic is switched over,
+providing an opportunity to test access and connectivity to online dependencies.
+This defaults to an HTTP request to the `GET /smoke` endpoint.
 
 ## Development
 
@@ -35,12 +66,27 @@ yarn format
 yarn lint
 ```
 
+### Start
+
+```shell
+# Start a local HTTP server
+yarn start
+
+# Start with Node.js Inspector enabled
+yarn start:debug
+```
+
 ### Deploy
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Branch commits can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Master commits are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+
+To rapidly roll back a change,
+retry an individual deployment step from the previous build in Buildkite.
+Note that this will introduce drift between the head of the default Git branch and the live environment;
+use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
@@ -63,3 +109,10 @@ TODO: add support links for the prod environment.
 - Datadog dashboard
 - Splunk logs
 -->
+
+[builds at seek]: https://builds-at-seek.ssod.skinfra.xyz
+[codedeploy]: https://docs.aws.amazon.com/codedeploy
+[codex]: https://codex.ssod.skinfra.xyz/docs
+[express]: https://expressjs.com
+[gantry]: https://gantry.ssod.skinfra.xyz
+[technology strategy]: https://tech-strategy.ssod.skinfra.xyz

template/greeter/README.md

@@ -2,29 +2,107 @@
 
 [![Powered by skuba](https://img.shields.io/badge/🤿%20skuba-powered-009DC4)](https://github.com/seek-oss/skuba)
 
-<!--
+Next steps:
+
+1. [ ] Finish templating if this was skipped earlier:
+
+   ```shell
+   yarn skuba configure
+   ```
+
+2. [ ] Create a new repository in the appropriate GitHub organisation.
+3. [ ] Add the repository to BuildAgency;
+       see [Builds at SEEK] for more information.
+4. [ ] Fill out [.me](.me) to power SEEK's system catalogue;
+       see the [Codex] documentation for more information.
+5. [ ] Push local commits to the upstream GitHub branch.
+6. [ ] Delete this checklist 😌.
 
 ## Table of contents
 
-- [Usage](#usage)
 - [Design](#design)
 - [Development](#development)
+  - [Test](#test)
+  - [Lint](#lint)
+  - [Start](#start)
+  - [Deploy](#deploy)
 - [Support](#support)
+  - [Dev](#dev)
+  - [Prod](#prod)
 
-## Usage
+## Design
 
-...
+The `greeter` template is the prototypical _hello world_ project.
+It can function as a playground for the TypeScript tooling prescribed by our [technology strategy],
+or serve as a starting point for a backend project if the other built-in templates are not a good fit.
 
-## Design
+It's a barebones Node.js application that comprises:
 
-...
+- A [src/app.ts] that can be run locally to greet the user
+- A [src/app.test.ts] that demonstrates rudimentary Jest usage
 
 ## Development
 
-...
+### Test
+
+```shell
+yarn test
+```
+
+### Lint
+
+```shell
+# Fix issues
+yarn format
+
+# Check for issues
+yarn lint
+```
+
+### Start
+
+```shell
+# Start a live-reloading process
+yarn start
+
+# Start with Node.js Inspector enabled
+yarn start:debug
+```
+
+This runs a live-reloading Node.js process pointing to the [src/app.ts](src/app.ts) entrypoint.
+
+## Deploy
+
+The `greeter` template includes a simple [Buildkite pipeline](.buildkite/pipeline.yml) for testing and linting.
+It does not assume a deployment method or environment.
+
+For inspiration in this space, check out:
+
+- The `koa-rest-api` template for containerised deployments
+- The `lambda-sqs-worker` template for Lambda deployments
 
 ## Support
 
-...
+### Dev
+
+TODO: add support links for the dev environment.
 
+<!--
+- CloudWatch dashboard
+- Datadog dashboard
+- Splunk logs
 -->
+
+### Prod
+
+TODO: add support links for the prod environment.
+
+<!--
+- CloudWatch dashboard
+- Datadog dashboard
+- Splunk logs
+-->
+
+[builds at seek]: https://builds-at-seek.ssod.skinfra.xyz
+[codex]: https://codex.ssod.skinfra.xyz/docs
+[technology strategy]: https://tech-strategy.ssod.skinfra.xyz

template/koa-rest-api/README.md

@@ -2,20 +2,56 @@
 
 [![Powered by skuba](https://img.shields.io/badge/🤿%20skuba-powered-009DC4)](https://github.com/seek-oss/skuba)
 
+Next steps:
+
+1. [ ] Finish templating if this was skipped earlier:
+
+   ```shell
+   yarn skuba configure
+   ```
+
+2. [ ] Create a new repository in the appropriate GitHub organisation.
+3. [ ] Add the repository to BuildAgency;
+       see [Builds at SEEK] for more information.
+4. [ ] Fill out [.me](.me) to power SEEK's system catalogue;
+       see the [Codex] documentation for more information.
+5. [ ] Add Datadog configuration and data classification tags to [.gantry/common.yml](.gantry/common.yml);
+       see the [Gantry] documentation for more information.
+6. [ ] Push local commits to the upstream GitHub branch.
+7. [ ] Delete this checklist 😌.
+
 ## Table of contents
 
 - [Design](#design)
 - [Development](#development)
   - [Test](#test)
   - [Lint](#lint)
+  - [Start](#start)
   - [Deploy](#deploy)
 - [Support](#support)
   - [Dev](#dev)
   - [Prod](#prod)
 
 ## Design
 
-TODO: explain the design of your API here.
+<%-repoName %> is a Node.js HTTP server built in line with our [technology strategy].
+It uses the [Koa] middleware framework and common SEEK packages.
+Resource APIs enable synchronous interactions and serve as the backbone of SEEK's general service architecture.
+
+The `koa-rest-api` template is modelled after a hypothetical service for posting and retrieving job advertisements.
+It's stubbed out with in-memory [storage](src/storage) which can observed by standing up an environment with multiple instances.
+Storage is local to each instance, so load balancing across the instances may render a read inconsistent with a previous write.
+This would be replaced with an external data store in production.
+
+This project is deployed as a containerised application with [Gantry].
+A typical resource API instance does not require more than 1 vCPU,
+so we eskew clustering configurations in favour of a single Node.js process per container.
+Under load, we autoscale horizontally in terms of container count up to `autoScaling.maxCount`.
+
+Gantry configures [CodeDeploy] for a blue-green deployment approach.
+A smoke test is run against the new version before traffic is switched over,
+providing an opportunity to test access and connectivity to online dependencies.
+This defaults to an HTTP request to the `GET /smoke` endpoint.
 
 ## Development
 
@@ -28,19 +64,34 @@ yarn test
 ### Lint
 
 ```shell
-# fix
+# Fix issues
 yarn format
 
-# check
+# Check for issues
 yarn lint
 ```
 
+### Start
+
+```shell
+# Start a local HTTP server
+yarn start
+
+# Start with Node.js Inspector enabled
+yarn start:debug
+```
+
 ### Deploy
 
 This project is deployed through a [Buildkite pipeline](.buildkite/pipeline.yml).
 
-- Branch commits can be deployed to the dev environment by unblocking a step in the Buildkite UI
-- Master commits are automatically deployed to the dev and prod environments in sequence
+- Commits to a feature branch can be deployed to the dev environment by unblocking a step in the Buildkite UI
+- Commits to the default branch are automatically deployed to the dev and prod environments in sequence
+
+To rapidly roll back a change,
+retry an individual deployment step from the previous build in Buildkite.
+Note that this will introduce drift between the head of the default Git branch and the live environment;
+use with caution and always follow up with a proper revert or fix in Git history.
 
 ## Support
 
@@ -63,3 +114,10 @@ TODO: add support links for the prod environment.
 - Datadog dashboard
 - Splunk logs
 -->
+
+[builds at seek]: https://builds-at-seek.ssod.skinfra.xyz
+[codedeploy]: https://docs.aws.amazon.com/codedeploy
+[codex]: https://codex.ssod.skinfra.xyz/docs
+[gantry]: https://gantry.ssod.skinfra.xyz
+[koa]: https://koajs.com
+[technology strategy]: https://tech-strategy.ssod.skinfra.xyz