From 507c69fdfadf145ab00881e1050d4bd293d192b3 Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Wed, 3 Dec 2025 12:39:41 +0000 Subject: [PATCH 1/4] docs: Add notes about development tools Adds notes about how to run the linter, renderer and mock server, as well as a suggestion they be run before opening a PR. --- CONTRIBUTING.md | 6 ++++-- README.md | 14 ++++++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 196d5dd3..6c0ed29e 100644 --- a/CONTRIBUTING.md +++ b/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) diff --git a/README.md b/README.md index 2b5e3615..df8e7a82 100644 --- a/README.md +++ b/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, and are primarily tested on Linux (but may work on other platforms). +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 + +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. From e647978f8b742f7ea2fab4adaf10e9ae37d35b5c Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Tue, 17 Feb 2026 10:56:55 +0000 Subject: [PATCH 2/4] ci: Bump pbrversion image version Bumps to a new version that now builds for ARM platforms as well --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index c2d871fa..56d7acc4 100644 --- a/Makefile +++ b/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 `..` semantic version. This repo only uses a `.` 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 From fea72c12fc8be72f51f679fb1c748e0b065543bd Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Tue, 17 Feb 2026 11:03:30 +0000 Subject: [PATCH 3/4] ci: Set platform for non-multiarch Docker images Handles upstream tool dependencies that don't build on `linux/arm64` so they (might!) still work in non-x86 environments. sem-ver: bugfix --- api/Makefile | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/api/Makefile b/api/Makefile index 32fc2036..d5fb0f77 100644 --- a/api/Makefile +++ b/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 From 63ce5cd04c0eaebb1b4f91257795029bf6eccbdf Mon Sep 17 00:00:00 2001 From: Sam Mesterton-Gibbons Date: Tue, 17 Feb 2026 11:25:16 +0000 Subject: [PATCH 4/4] docs: Mention platform requirements of tools --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index df8e7a82..24583648 100644 --- a/README.md +++ b/README.md @@ -219,7 +219,7 @@ These documents may be found in the [docs/adr](./docs/adr/) directory, and are m ### Development This repository contains a [Makefile](./Makefile) with various targets to aid specification development. -These rely on having Docker available on the system, and are primarily tested on Linux (but may work on other platforms). +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: