docs: Add notes about development tools

CONTRIBUTING.md

@@ -22,8 +22,10 @@ The process is:
       - `sem-ver: feature` - where a new feature has been added
       - `sem-ver: deprecation` - where an existing feature has been marked as deprecated, but not yet removed
 4. If you haven't already done so, sign the CLA (see below)
-5. Open a Pull Request with your changes.
-   Don't worry about leaving empty spaces on the PR template (it's aimed at internal contributions), just fill in the description
+5. Prior to opening a Pull Request you may wish to run the linter with `make lint`: see [Development](./README.md#development) for more on the targets available
+6. Open a Pull Request with your changes.
+   Don't worry about leaving empty spaces on the PR template (it's aimed at internal contributions), just fill in the description.
+   A maintainer will review your changes, and trigger the CI process.
 
 ## Contributor Licence Agreement (CLA)
 

Makefile

@@ -2,7 +2,7 @@ NUM_OF_PARENT:=$(shell echo $$(( $(words $(MAKEFILE_LIST)))) )
 topdir:=$(realpath $(dir $(word $(NUM_OF_PARENT),$(MAKEFILE_LIST))))
 
 # pbrversion calculates versions based on git tags, number of commits since the most recent tag, magic strings in commit messages to signal types of changes. Magic strings are of the form `Sem-Ver: ` followed by one of `feature`, `api-break`, `deprecation`, and `bugfix`. pbrversion returns a `<major>.<minor>.<patch>` semantic version. This repo only uses a `<major>.<minor>` version, so the last component is stripped using make's `basename` function.
-NEXT_VERSION := $(basename $(shell docker run --rm -v $(topdir):/data:ro public.ecr.aws/o4o2s1w1/cloudfit/pbrversion:1.4.1 --brief))
+NEXT_VERSION := $(basename $(shell docker run --rm -v $(topdir):/data:ro public.ecr.aws/o4o2s1w1/cloudfit/pbrversion:1.4.2 --brief))
 
 all: help
 

README.md

@@ -216,6 +216,20 @@ It is assumed that implementations will apply other IT and cloud infrastructure
 This repository uses [(M)ADR documents](https://adr.github.io/madr/) to propose significant changes, facilitate discussions and decision making, and to store a record of options that were considered.
 These documents may be found in the [docs/adr](./docs/adr/) directory, and are managed as described by the [ADR Readme](./docs/adr/README.md).
 
+### Development
+
+This repository contains a [Makefile](./Makefile) with various targets to aid specification development.
+These rely on having Docker available on the system, are primarily tested on Linux and some of the images used are only built for x86-64 platforms, however other operating systems and platforms may work using emulation.
+Linting and documentation rendering are also handled by GitHub Actions when Pull Requests are submitted and merged.
+
+The following targets are available:
+
+- `make lint` - Lint Markdown documents, validate API specifications, examples and schemas
+- `make render` - Generate HTML rendered version of OpenAPI spec (at `api/docs/index.html`)
+- `make mock-server-up` - Start a mock TAMS API on <http://localhost:4010/?access_token=fake>
+
+Note that for the mock server, some credentials must be supplied to meet the spec; either an `Authorization` header for HTTP Basic/Bearer token, or an `access_token` query string.
+
 ## Making a release
 
 Run the `release` workflow under the `Actions` tab on this repository on GitHub against the `main` branch.

api/Makefile

@@ -5,11 +5,11 @@ all: help
 
 
 build-lint:
-	docker pull stoplight/spectral:6.10 >/dev/null 2>/dev/null || true
-	DOCKER_BUILDKIT=1 docker build -f Dockerfile.multi --target oaslint -t tams_api_oaslint:local .
+	docker pull --platform linux/amd64 stoplight/spectral:6.10 >/dev/null 2>/dev/null || true
+	DOCKER_BUILDKIT=1 docker build --platform linux/amd64 -f Dockerfile.multi --target oaslint -t tams_api_oaslint:local .
 
 lint: build-lint
-	docker run --rm tams_api_oaslint:local lint --fail-severity=warn /data/TimeAddressableMediaStore.yaml
+	docker run --platform linux/amd64 --rm tams_api_oaslint:local lint --fail-severity=warn /data/TimeAddressableMediaStore.yaml
 
 
 build-bundle:
@@ -23,8 +23,8 @@ render: docs/TimeAddressableMediaStore_bundled.yaml
 
 
 mock-server-up:
-	docker pull stoplight/prism >/dev/null 2>/dev/null || true
-	docker run --rm --init --name mock-tams -v "${topdir}":/data:ro -p 4010:4010 stoplight/prism mock /data/TimeAddressableMediaStore.yaml -h 0.0.0.0
+	docker pull --platform linux/amd64 stoplight/prism >/dev/null 2>/dev/null || true
+	docker run --platform linux/amd64 --rm --init --name mock-tams -v "${topdir}":/data:ro -p 4010:4010 stoplight/prism mock /data/TimeAddressableMediaStore.yaml -h 0.0.0.0
 
 mock-server-down:
 	docker stop mock-tams