CCM-11207: need a spec to gen from

Author: masl2

docs/_config.yml

@@ -53,7 +53,7 @@ just_the_docs:
       # Supports true or false (default)
       nav_fold: false # note: this option is new in v0.4
       # Exclude the collection from the search
-      # Supports true or false (defaul
+      # Supports true or false (default)
       search_exclude: false
 
 defaults:

docs/collections/_developers/architecture-design/design-index.md

@@ -1,7 +1,6 @@
 ---
 title: Architecture & Design
-order: 0
-nav_order: 5
+nav_order: 2
 has_children: true
 has_toc: true
 ---

docs/collections/_developers/getting-started.md

@@ -1,7 +1,7 @@
 ---
 title: API Developers - Getting Started
 order: 0
-nav_order: 4
+nav_order: 1
 has_children: false
 has_toc: false
 ---

docs/collections/_developers/guides/bash-and-make.md

@@ -0,0 +1,157 @@
+---
+
+title:  Bash and Make
+parent: Developer Guides
+---
+
+## Developer Guide: Bash and Make
+
+- [Developer Guide: Bash and Make](#developer-guide-bash-and-make)
+  - [Using Make](#using-make)
+  - [Using Bash](#using-bash)
+  - [Make and Bash working together](#make-and-bash-working-together)
+  - [Conventions](#conventions)
+    - [Debugging](#debugging)
+    - [Scripts](#scripts)
+
+## Using Make
+
+Sample make target signature definition:
+
+```makefile
+some-target: # Target description - mandatory: foo=[description]; optional: baz=[description, default is 'qux'] @Category
+    # Recipe implementation...
+```
+
+- `some-target`: This is the name of the target you would specify when you want to run this particular target. Use the kebab-case naming convention and prefix with an underscore `_` to mark it as a "private" target. The first part of the name is used for grouping, e.g. `docker-*` or `terraform-*`.
+- `Target Description`: Provided directly after the target name as a single line, so be concise.
+- `mandatory` parameters: Parameters that must be provided when invoking the target. Each parameter has its own description. Please follow the specified format as it is used by `make help`.
+- `optional` parameters: Parameters that are not required when invoking the target. They may have a default value. Each parameter has its own description.
+- `@Category` label: Used for grouping by the `make help` command.
+- `Recipe implementation`: This section defines the actual commands or steps the target will execute. **Do not exceed 5 lines of effective code**. For more complex operations, use a shell script. Refer to the `docker-build` implementation in the [docker.mk](../../scripts/docker/docker.mk) file. More complex operations are implemented in the [docker.sh](../../scripts/docker/docker.lib.sh) script for readability and simplicity.
+
+Run make target from a terminal:
+
+```shell
+foo=bar make some-target # Environment variable is passed to the make target execution process
+make some-target foo=bar # Make argument is passed to the make target execution process
+```
+
+By convention we use uppercase variables for global settings that you would ordinarily associate with environment variables. We use lower-case variables as arguments to call functions or make targets, in this case.
+
+All make targets should be added to the `${VERBOSE}.SILENT:` section of the `make` file, which prevents `make` from printing commands before executing them. The `${VERBOSE}` prefix on the `.SILENT:` special target allows toggling it if needed. If you explicitly want output from a certain line, use `echo`.
+
+It is worth noting that by default, `make` creates a new system process to execute each line of a recipe. This is not the desired behaviour for us and the entire content of a make recipe (a target) should be run in a single shell invocation. This has been configured in this repository by setting the [`.ONESHELL:`](https://www.gnu.org/software/make/manual/html_node/One-Shell.html) special target in the `scripts/init.mk` file.
+
+To see all available make targets, run `make help`.
+
+## Using Bash
+
+When working in the command-line ensure the environment variables are reset to their initial state. This can be done by reloading shell using the `env -i $SHELL` command.
+
+Sample Bash function definition:
+
+```shell
+# Short function description
+# Arguments (provided as environment variables):
+#   foo=[description]
+#   baz=[description, default is 'qux']
+function some-shell-function() {
+    # Function implementation...
+```
+
+Run Bash function from a terminal:
+
+```shell
+source scripts/a-suite-of-shell-functions
+foo=bar some-shell-function # Environment variable is accessible by the function executed in the same operating system process
+```
+
+```shell
+source scripts/a-suite-of-shell-functions
+foo=bar
+some-shell-function # Environment variable is still accessible by the function
+```
+
+Run Bash script from a terminal, bear in mind that executing a script creates a child operating system process:
+
+```shell
+# Environment variable has to be exported to be passed to a child process, DO NOT use this pattern
+export foo=bar
+scripts/a-shell-script
+```
+
+```shell
+# or to be set in the same line before creating a new process, prefer this pattern over the previous one
+foo=bar scripts/a-shell-script
+
+# or when multiple variables are required
+foo=bar \
+baz=qux \
+  scripts/a-shell-script
+```
+
+By convention we use uppercase variables for global settings that you would ordinarily associate with environment variables. We use lower-case variables as arguments to be passed into specific functions we call, usually on the same line, right before the function name.
+
+The command `set -euo pipefail` is commonly used in the Bash scripts, to configure the behavior of the script in a way that makes it more robust and easier to debug. Here is a breakdown of each option switch:
+
+- `-e`: Ensures that the script exits immediately if any command returns a non-zero exit status.
+- `-u`: Makes the script exit if there is an attempt to use an uninitialised variable.
+- `-o pipefail`: ensures that if any command in a pipeline fails (i.e., returns a non-zero exit status), then the entire pipeline will return that non-zero status. By default, a pipeline returns the exit status of the last command.
+
+## Make and Bash working together
+
+Sample make target calling a Bash function. Notice that `baz` is going to be accessible to the function as it is executed in the same operating system process:
+
+```makefile
+some-target: # Run shell function - mandatory: foo=[description]
+  source scripts/a-suite-of-shell-function
+  baz=qux
+  some-shell-function # 'foo' and 'baz' are accessible by the function
+```
+
+Sample make target calling another make target. In this case a parameter `baz` has to be passed as a variable to the make target, which is executed in a child process:
+
+```makefile
+some-target: # Call another target - mandatory: foo=[description]
+  baz=qux \
+    make another-target # 'foo' and 'baz' are passed to the make target
+```
+
+Run it from a terminal:
+
+```shell
+foo=bar make some-target
+```
+
+## Conventions
+
+### Debugging
+
+To assist in investigating scripting issues, the `VERBOSE` variable is available for both Make and Bash scripts. If it is set to `true` or `1`, it prints all the commands that the script executes to the standard output. Here is how to use it:
+
+for Make targets
+
+```shell
+VERBOSE=1 make docker-example-build
+```
+
+for Bash scripts
+
+```shell
+VERBOSE=1 scripts/shellscript-linter.sh
+```
+
+### Scripts
+
+Most scripts provided with this repository template can use tools installed on your `PATH` if they are available or run them from within a Docker container. To force a script to use Docker, the `FORCE_USE_DOCKER` variable is provided. This feature allows you to use custom tooling if it is present on the command-line path. Here is how to use it:
+
+```shell
+FORCE_USE_DOCKER=1 scripts/shellscript-linter.sh
+```
+
+You can combine it with the `VERBOSE` flag to see the details of the execution flow:
+
+```shell
+VERBOSE=1 FORCE_USE_DOCKER=1 scripts/shellscript-linter.sh
+```

docs/collections/_developers/guides/dev-guides.md

@@ -0,0 +1,6 @@
+---
+title: Developer Guides
+nav_order: 3
+has_children: true
+has_toc: true
+---

docs/collections/_developers/guides/git.md

@@ -0,0 +1,7 @@
+---
+title: Git
+parent: Developer Guides
+description: Getting started with Git
+summary: Getting started with Git
+last_modified_date: 2024-05-28
+---

docs/collections/_developers/guides/github.md

@@ -0,0 +1,116 @@
+---
+title: GitHub Configuration
+parent: Developer Guides
+description: Configuring new GitHub repositories for use within NHS Notify
+summary: Configuring new GitHub repositories for use within NHS Notify
+last_modified_date: 2024-05-28
+---
+
+When setting up a new GitHub repository for use with NHS Notify, we use a standard set of configuration options to
+ensure consistency and security.
+
+This guide follows the NHSE Software Engineering Quality Framework, in particular the following pages are useful:
+
+* [Securing Repositories](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/securing-repositories.md#securing-repositories)
+* [Continuous Integration](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/continuous-integration.md)
+
+## Codeowners
+
+Following
+the [SEQF guidance](https://github.com/NHSDigital/software-engineering-quality-framework/blob/main/practices/securing-repositories.md#teams-setup),
+the default code owner should be the GitHub team with write access to the repository.
+
+In addition, due to the multi-repository structure of the codebase, the CODEOWNERS files themselves are protected by
+requiring approval from a project-wide nhs-notify-code-owners team.
+
+For example:
+
+```codeowners
+# Default codeowner should be a team with write access
+*                     @NHSDigital/nhs-notify-amet
+
+# Default protection for codeowners, must be last in file
+/.github/CODEOWNERS   @NHSDigital/nhs-notify-code-owners
+/CODEOWNERS           @NHSDigital/nhs-notify-code-owners
+```
+
+Individual teams are encouraged to include additional codeowners for any sub-components of their repository which
+require additional scrutiny.
+
+## Runners
+
+* [Do not use private runners for public repos](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security)
+* We will use GitHub hosted runners for CI in all public repos
+* We will also use GitHub hosted runners for private repos unless we have a good reason that a private runner is needed
+
+## Branch Protection Rules
+
+* Allow Squash merges - this should be the default merge type for feature branches
+* Allow merge commits - this may be required for release or hotfix branches to be merged back to main
+* Require signed commits
+* Optional: merge queues may be used if merge frequency causes issues for a repository
+* Use branch protection rules - rulesets are currently not recognised by the engineering quality dashboard
+  * `main` branch should be protected from deletion
+  * Require a pull request before merging
+  * Require approvals
+  * Dismiss stale pull request approvals when new commits are pushed
+  * Require review from Code Owners
+  * Require approval of the most recent reviewable push
+  * Require status checks to pass before merging
+  * Require conversation resolution before merging
+  * Require signed commits
+
+## Pull requests for public repos
+
+* [Pull requests from forked repos should be configured to require a maintainer to approve the workflow run for all outside contributors](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#controlling-changes-from-forks-to-workflows-in-public-repositories)
+* Workflow runs for PRs from forked repos run with READ_ONLY permission by default, which means they do not have access
+  to secrets and cannot make any modifications to the base repo.
+
+![fork-workflow-approval.png](assets/fork-workflow-approval.png)
+
+## Bootstrapping CI/CD
+
+* Public repositories should not directly invoke CD workflows, and should delegate to a private deployment repository.
+* [CD workflows should be granted access to an AWS deployment role via OIDC](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services)
+  * IAM allows a new OIDC identity provider to be registered with an account
+  * A role must be created with a trust policy allowing the GitHub repo token to assume the role.
+  * [Example of assuming a role using OIDC in an Actions workflow](https://medium.com/@thiagosalvatore/using-terraform-to-connect-github-actions-and-aws-with-oidc-0e3d27f00123)
+  * The set up of the necessary OIDC provider can be applied via Terraform
+  * This step is likely to require local deployment, although it's possible we could apply the changes from inside the AWS
+    console using cloudshell - TBD
+* Workflow files should be protected by the CODEOWNERS file to prevent unexpected modifications
+
+## CI Workflows
+
+* CI workflows should not require access to secrets
+* CI workflows should not require access to AWS resources
+* Component tests should use locally provisioned resources (docker containers or similar) or in-process test harnesses
+  to provide mock services
+* Contract tests should be implemented the same way
+* Micro-benchmarks on the service should be implemented the same way
+
+## CD Workflows
+
+* Deployment workflows may be triggered by users with appropriate access to the repository
+* Deployment workflows should be configured to work with the GitHub environments feature
+* [Deployment rules should be set appropriately for the environment being deployed](https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules)
+* Any secrets required for deployment should be set at the environment level. These will not be made available to any
+  workflows unless the deployment is approved
+
+## Post-deployment Workflows
+
+* Post-deployment workflows should be triggered after CD workflows or manually as needed
+* These workflows should be scoped to an environment in the same way as CD workflows
+* For individual services the post-deployment workflows should test behaviour at the domain boundary
+* E.g. the test should replay a scenario and subscribe to output events to ensure the behaviour is as expected
+* Service level benchmarking could be performed at this point in non-production environments
+* Full-platform end-to-end and performance tests should live in a separate repository
+
+## Artifacts and Releases
+
+* Artifacts for each build should be packaged and available from the CI pipeline output
+* These are available for 90 days in public repos (could be extended to 400 days in private repos)
+* When a tag is created, a release corresponding to that tag should publish the packaged artifacts
+* Deployment pipelines should either be triggered from a branch or a tag
+* When triggered from a branch, the most recent build for that branch should be used as the source of the artifacts
+* When triggered from a tag, the published release artifacts should be used