diff --git a/.github/workflows/docs-toc.yml b/.github/workflows/docs-toc.yml index 99570487a..589be02c6 100644 --- a/.github/workflows/docs-toc.yml +++ b/.github/workflows/docs-toc.yml @@ -1,21 +1,20 @@ -# TODO(thane): Re-enable once we've pulled in the ADRs and RFCs from master. # Verify that important design docs have ToC entries. -#name: Check documentation ToC -#on: -# pull_request: -# push: -# branches: -# - main -# -#jobs: -# check: -# runs-on: ubuntu-latest -# steps: -# - uses: actions/checkout@v3 -# - uses: technote-space/get-diff-action@v6 -# with: -# PATTERNS: | -# docs/architecture/** -# docs/rfc/** -# - run: ./docs/presubmit.sh -# if: env.GIT_DIFF +name: Check documentation ToC +on: + pull_request: + push: + branches: + - main + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + - uses: technote-space/get-diff-action@v6 + with: + PATTERNS: | + docs/architecture/** + docs/rfc/** + - run: make check-docs-toc + if: env.GIT_DIFF diff --git a/Makefile b/Makefile index 50457fb0d..75887c6b0 100644 --- a/Makefile +++ b/Makefile @@ -289,6 +289,11 @@ sync-docs: aws cloudfront create-invalidation --distribution-id ${CF_DISTRIBUTION_ID} --profile terraform --path "/*" ; .PHONY: sync-docs +# Verify that important design docs have ToC entries. +check-docs-toc: + @./docs/presubmit.sh +.PHONY: check-docs-toc + ############################################################################### ### Docker image ### ############################################################################### diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 9e1219060..e75896f38 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -77,7 +77,7 @@ Note the context/background should be written in the present tense. - [ADR-006: Trust-Metric](./adr-006-trust-metric.md) - [ADR-024: Sign-Bytes](./adr-024-sign-bytes.md) - [ADR-035: Documentation](./adr-035-documentation.md) -- [ADR-039: Peer-Behaviour](./adr-039-peer-behavior.md) +- [ADR-039: Peer-Behaviour](./adr-039-peer-behaviour.md) - [ADR-060: Go-API-Stability](./adr-060-go-api-stability.md) - [ADR-061: P2P-Refactor-Scope](./adr-061-p2p-refactor-scope.md) - [ADR-065: Custom Event Indexing](./adr-065-custom-event-indexing.md) diff --git a/docs/presubmit.sh b/docs/presubmit.sh new file mode 100755 index 000000000..0dec7d32a --- /dev/null +++ b/docs/presubmit.sh @@ -0,0 +1,39 @@ +#!/bin/bash +# +# This script verifies that each document in the docs and architecture +# directory has a corresponding table-of-contents entry in its README file. +# +# This can be run manually from the command line. +# It is also run in CI via the docs-toc.yml workflow. +# +set -euo pipefail + +readonly base="$(dirname $0)" +cd "$base" + +readonly workdir="$(mktemp -d)" +trap "rm -fr -- '$workdir'" EXIT + +checktoc() { + local dir="$1" + local tag="$2"'-*-*' + local out="$workdir/${dir}.out.txt" + ( + cd "$dir" >/dev/null + find . -maxdepth 1 -type f -name "$tag" -not -exec grep -q "({})" README.md ';' -print + ) > "$out" + if [[ -s "$out" ]] ; then + echo "-- The following files in $dir lack a ToC entry: +" + cat "$out" + return 1 + fi +} + +err=0 + +# Verify that each RFC and ADR has a ToC entry in its README file. +checktoc architecture adr || ((err++)) +checktoc rfc rfc || ((err++)) + +exit $err