Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
.build-cache/
_build
__pycache__/
39 changes: 27 additions & 12 deletions Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -14,20 +14,34 @@ FE ?= fe
FE_REPO ?= argotorg/fe
FE_SRC ?= $(error FE_SRC required — path to local clone of $(FE_REPO))
BUILD := _build
VERSION_RE := ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?(\+[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$$

# Keep command-line values literal when make exports them to recipe shells.
override TAG := $(value TAG)
override T := $(value T)
override VERSION := $(value VERSION)
override OUTDIR := $(value OUTDIR)
export TAG T VERSION OUTDIR

SHELL := /bin/bash
.SHELLFLAGS := -euo pipefail -c

.PHONY: build build-all build-stable deploy list clean
.PHONY: build build-all build-stable deploy list clean test

test:
@python3 -m unittest discover -s tests

build:
ifndef TAG
$(error TAG required. Usage: make build TAG=v26.0.0 FE_SRC=../fe FE=path/to/fe)
endif
@$(MAKE) --no-print-directory _build-tag T=$(TAG)
@tag="$${TAG}"; \
[[ "$$tag" == v* && "$${tag#v}" =~ $(VERSION_RE) ]] || { echo "Invalid release tag: $$tag" >&2; exit 1; }; \
T="$$tag" $(MAKE) --no-print-directory _build-tag

_build-tag:
@tag="$(T)"; \
@tag="$${T}"; \
[[ "$$tag" == v* && "$${tag#v}" =~ $(VERSION_RE) ]] || { echo "Invalid release tag: $$tag" >&2; exit 1; }; \
version="$${tag#v}"; \
if [ -f "$${version}/docs.json.gz" ] && [ -z "$(FORCE)" ]; then \
echo "SKIP $$tag"; \
Expand Down Expand Up @@ -55,16 +69,17 @@ endif
ifndef OUTDIR
$(error OUTDIR required — directory containing docs.json, fe-web.js, etc.)
endif
@echo "Deploying Fe $(VERSION) docs..."
@[[ "$$VERSION" =~ $(VERSION_RE) ]] || { echo "Invalid release version: $$VERSION" >&2; exit 1; }
@echo "Deploying Fe $$VERSION docs..."
@for f in fe-web.js fe-highlight.css styles.css; do \
[ -f "$(OUTDIR)/$$f" ] && cp "$(OUTDIR)/$$f" "./$$f" && echo " Updated $$f" || true; \
[ -f "$$OUTDIR/$$f" ] && cp "$$OUTDIR/$$f" "./$$f" && echo " Updated $$f" || true; \
done
@mkdir -p "$(VERSION)"
@gzip -c "$(OUTDIR)/docs.json" > "$(VERSION)/docs.json.gz"
@sed 's|{{VERSION}}|$(VERSION)|g' _template/index.html > "$(VERSION)/index.html"
@echo " Created $(VERSION)/ ($$(du -h "$(VERSION)/docs.json.gz" | cut -f1))"
@mkdir -p "$$VERSION"
@gzip -c "$$OUTDIR/docs.json" > "$$VERSION/docs.json.gz"
@sed "s|{{VERSION}}|$$VERSION|g" _template/index.html > "$$VERSION/index.html"
@echo " Created $$VERSION/ ($$(du -h "$$VERSION/docs.json.gz" | cut -f1))"
@[ -f versions.json ] || echo '{"latest":"","versions":[]}' > versions.json
@jq --arg v "$(VERSION)" \
@jq --arg v "$$VERSION" \
'if (.versions | index($$v)) then . else .versions += [$$v] end | .latest = ([.versions[] | select(test("^[0-9]+\\.[0-9]+\\.[0-9]+$$"))] | sort_by(split(".") | map(tonumber)) | last // .versions[0])' \
Comment on lines +82 to 83

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Handle an initial prerelease when choosing latest

When versions.json has no stable versions, deploying a permitted prerelease or build-metadata version fails here with Cannot index array with string "versions". After the inner pipeline reaches last, the fallback .versions[0] is evaluated against that pipeline's array rather than the root object, so the command exits after creating the version artifacts but leaves versions.json unchanged. The new test misses this because it always deploys a stable version before the prerelease.

Useful? React with 👍 / 👎.

versions.json > versions.json.tmp && mv versions.json.tmp versions.json
@echo " versions.json: latest=$$(jq -r '.latest' versions.json), $$(jq '.versions | length' versions.json) versions"
Expand All @@ -74,7 +89,7 @@ build-stable:
tags=$$(gh release list --repo $(FE_REPO) --limit 100 --json tagName --jq '.[].tagName | select(startswith("v2") and test("^v[0-9]+\\.[0-9]+\\.[0-9]+$$"))'); \
failed=0; \
for tag in $$tags; do \
$(MAKE) --no-print-directory _build-tag T=$$tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
T="$$tag" $(MAKE) --no-print-directory _build-tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
done; \
echo ""; \
if [ $$failed -gt 0 ]; then \
Expand All @@ -88,7 +103,7 @@ build-all:
tags=$$(gh release list --repo $(FE_REPO) --limit 100 --json tagName --jq '.[].tagName | select(startswith("v2"))'); \
failed=0; \
for tag in $$tags; do \
$(MAKE) --no-print-directory _build-tag T=$$tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
T="$$tag" $(MAKE) --no-print-directory _build-tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
done; \
echo ""; \
if [ $$failed -gt 0 ]; then \
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,8 +33,10 @@ The `FE_SRC` path is used to `git archive` the stdlib sources for each tag. The

## CI

New releases trigger the `docs` job in the fe repo's CI. It downloads the release binary, generates docs, and pushes here via `make deploy`.
New releases trigger the fe repo's CI to download the release binary, generate docs, and publish them here via `make deploy`.

## Deploy target

`make deploy VERSION=26.0.0 OUTDIR=/tmp/docs-out` copies build artifacts into the site structure. Called by both `make build` and CI.

`VERSION` must be a numeric release version, optionally followed by a prerelease or build-metadata suffix, such as `26.0.0-alpha.2`.
77 changes: 77 additions & 0 deletions tests/test_deploy.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
import gzip
import json
import shutil
import subprocess
import tempfile
import unittest
from pathlib import Path


ROOT = Path(__file__).resolve().parents[1]


class DeployTests(unittest.TestCase):
def setUp(self):
self.temp = tempfile.TemporaryDirectory()
self.addCleanup(self.temp.cleanup)
self.site = Path(self.temp.name)
shutil.copy2(ROOT / "Makefile", self.site / "Makefile")
shutil.copytree(ROOT / "_template", self.site / "_template")
(self.site / "versions.json").write_text('{"latest":"","versions":[]}')
self.output = self.site / "output"
self.output.mkdir()
(self.output / "docs.json").write_text('{"index":{}}')
for name in ("fe-web.js", "fe-highlight.css", "styles.css"):
(self.output / name).write_text(name)

def make(self, target, variable):
return subprocess.run(
["make", target, variable, f"OUTDIR={self.output}"],
cwd=self.site,
capture_output=True,
text=True,
check=False,
)

def test_deploys_stable_and_prerelease_versions(self):
for version in ("26.3.0", "26.3.1-alpha.2"):
with self.subTest(version=version):
result = self.make("deploy", f"VERSION={version}")
self.assertEqual(result.returncode, 0, result.stderr)
with gzip.open(self.site / version / "docs.json.gz", "rt") as docs:
self.assertEqual(json.load(docs), {"index": {}})
self.assertIn(version, (self.site / version / "index.html").read_text())
versions = json.loads((self.site / "versions.json").read_text())
self.assertEqual(versions["latest"], "26.3.0")
self.assertEqual(versions["versions"], ["26.3.0", "26.3.1-alpha.2"])

def test_rejects_make_and_shell_substitution(self):
marker = self.site / "executed"
for payload in (
f"26.3.0$(shell touch {marker})",
f"26.3.0$(touch {marker})",
"../escape",
):
with self.subTest(payload=payload):
result = self.make("deploy", f"VERSION={payload}")
self.assertNotEqual(result.returncode, 0)
self.assertFalse(marker.exists())

def test_rejects_unsafe_tag_before_building(self):
marker = self.site / "executed"
tag = f"v26.3.0$(shell touch {marker})"
for target, variable in (("build", f"TAG={tag}"), ("_build-tag", f"T={tag}")):
with self.subTest(target=target):
result = subprocess.run(
["make", target, variable, f"FE_SRC={self.site}"],
cwd=self.site,
capture_output=True,
text=True,
check=False,
)
self.assertNotEqual(result.returncode, 0)
self.assertFalse(marker.exists())


if __name__ == "__main__":
unittest.main()