Skip to content

Commit c6147ef

Browse files
committed
Treat release versions as data in docs deployment
1 parent 94d1a87 commit c6147ef

4 files changed

Lines changed: 107 additions & 12 deletions

File tree

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
.build-cache/
22
_build
3+
__pycache__/

‎Makefile‎

Lines changed: 27 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,20 +14,34 @@ FE ?= fe
1414
FE_REPO ?= argotorg/fe
1515
FE_SRC ?= $(error FE_SRC required — path to local clone of $(FE_REPO))
1616
BUILD := _build
17+
VERSION_RE := ^([0-9]+\.){2}[0-9]+(-[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?(\+[0-9A-Za-z]+([.-][0-9A-Za-z]+)*)?$$
18+
19+
# Keep command-line values literal when make exports them to recipe shells.
20+
override TAG := $(value TAG)
21+
override T := $(value T)
22+
override VERSION := $(value VERSION)
23+
override OUTDIR := $(value OUTDIR)
24+
export TAG T VERSION OUTDIR
1725

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

21-
.PHONY: build build-all build-stable deploy list clean
29+
.PHONY: build build-all build-stable deploy list clean test
30+
31+
test:
32+
@python3 -m unittest discover -s tests
2233

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

2942
_build-tag:
30-
@tag="$(T)"; \
43+
@tag="$${T}"; \
44+
[[ "$$tag" == v* && "$${tag#v}" =~ $(VERSION_RE) ]] || { echo "Invalid release tag: $$tag" >&2; exit 1; }; \
3145
version="$${tag#v}"; \
3246
if [ -f "$${version}/docs.json.gz" ] && [ -z "$(FORCE)" ]; then \
3347
echo "SKIP $$tag"; \
@@ -55,16 +69,17 @@ endif
5569
ifndef OUTDIR
5670
$(error OUTDIR required — directory containing docs.json, fe-web.js, etc.)
5771
endif
58-
@echo "Deploying Fe $(VERSION) docs..."
72+
@[[ "$$VERSION" =~ $(VERSION_RE) ]] || { echo "Invalid release version: $$VERSION" >&2; exit 1; }
73+
@echo "Deploying Fe $$VERSION docs..."
5974
@for f in fe-web.js fe-highlight.css styles.css; do \
60-
[ -f "$(OUTDIR)/$$f" ] && cp "$(OUTDIR)/$$f" "./$$f" && echo " Updated $$f" || true; \
75+
[ -f "$$OUTDIR/$$f" ] && cp "$$OUTDIR/$$f" "./$$f" && echo " Updated $$f" || true; \
6176
done
62-
@mkdir -p "$(VERSION)"
63-
@gzip -c "$(OUTDIR)/docs.json" > "$(VERSION)/docs.json.gz"
64-
@sed 's|{{VERSION}}|$(VERSION)|g' _template/index.html > "$(VERSION)/index.html"
65-
@echo " Created $(VERSION)/ ($$(du -h "$(VERSION)/docs.json.gz" | cut -f1))"
77+
@mkdir -p "$$VERSION"
78+
@gzip -c "$$OUTDIR/docs.json" > "$$VERSION/docs.json.gz"
79+
@sed "s|{{VERSION}}|$$VERSION|g" _template/index.html > "$$VERSION/index.html"
80+
@echo " Created $$VERSION/ ($$(du -h "$$VERSION/docs.json.gz" | cut -f1))"
6681
@[ -f versions.json ] || echo '{"latest":"","versions":[]}' > versions.json
67-
@jq --arg v "$(VERSION)" \
82+
@jq --arg v "$$VERSION" \
6883
'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])' \
6984
versions.json > versions.json.tmp && mv versions.json.tmp versions.json
7085
@echo " versions.json: latest=$$(jq -r '.latest' versions.json), $$(jq '.versions | length' versions.json) versions"
@@ -74,7 +89,7 @@ build-stable:
7489
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]+$$"))'); \
7590
failed=0; \
7691
for tag in $$tags; do \
77-
$(MAKE) --no-print-directory _build-tag T=$$tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
92+
T="$$tag" $(MAKE) --no-print-directory _build-tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
7893
done; \
7994
echo ""; \
8095
if [ $$failed -gt 0 ]; then \
@@ -88,7 +103,7 @@ build-all:
88103
tags=$$(gh release list --repo $(FE_REPO) --limit 100 --json tagName --jq '.[].tagName | select(startswith("v2"))'); \
89104
failed=0; \
90105
for tag in $$tags; do \
91-
$(MAKE) --no-print-directory _build-tag T=$$tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
106+
T="$$tag" $(MAKE) --no-print-directory _build-tag FORCE="$(FORCE)" || failed=$$((failed + 1)); \
92107
done; \
93108
echo ""; \
94109
if [ $$failed -gt 0 ]; then \

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,3 +38,5 @@ New releases trigger the `docs` job in the fe repo's CI. It downloads the releas
3838
## Deploy target
3939

4040
`make deploy VERSION=26.0.0 OUTDIR=/tmp/docs-out` copies build artifacts into the site structure. Called by both `make build` and CI.
41+
42+
`VERSION` must be a numeric release version, optionally followed by a prerelease or build-metadata suffix, such as `26.0.0-alpha.2`.

‎tests/test_deploy.py‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
import gzip
2+
import json
3+
import shutil
4+
import subprocess
5+
import tempfile
6+
import unittest
7+
from pathlib import Path
8+
9+
10+
ROOT = Path(__file__).resolve().parents[1]
11+
12+
13+
class DeployTests(unittest.TestCase):
14+
def setUp(self):
15+
self.temp = tempfile.TemporaryDirectory()
16+
self.addCleanup(self.temp.cleanup)
17+
self.site = Path(self.temp.name)
18+
shutil.copy2(ROOT / "Makefile", self.site / "Makefile")
19+
shutil.copytree(ROOT / "_template", self.site / "_template")
20+
(self.site / "versions.json").write_text('{"latest":"","versions":[]}')
21+
self.output = self.site / "output"
22+
self.output.mkdir()
23+
(self.output / "docs.json").write_text('{"index":{}}')
24+
for name in ("fe-web.js", "fe-highlight.css", "styles.css"):
25+
(self.output / name).write_text(name)
26+
27+
def make(self, target, variable):
28+
return subprocess.run(
29+
["make", target, variable, f"OUTDIR={self.output}"],
30+
cwd=self.site,
31+
capture_output=True,
32+
text=True,
33+
check=False,
34+
)
35+
36+
def test_deploys_stable_and_prerelease_versions(self):
37+
for version in ("26.3.0", "26.3.1-alpha.2"):
38+
with self.subTest(version=version):
39+
result = self.make("deploy", f"VERSION={version}")
40+
self.assertEqual(result.returncode, 0, result.stderr)
41+
with gzip.open(self.site / version / "docs.json.gz", "rt") as docs:
42+
self.assertEqual(json.load(docs), {"index": {}})
43+
self.assertIn(version, (self.site / version / "index.html").read_text())
44+
versions = json.loads((self.site / "versions.json").read_text())
45+
self.assertEqual(versions["latest"], "26.3.0")
46+
self.assertEqual(versions["versions"], ["26.3.0", "26.3.1-alpha.2"])
47+
48+
def test_rejects_make_and_shell_substitution(self):
49+
marker = self.site / "executed"
50+
for payload in (
51+
f"26.3.0$(shell touch {marker})",
52+
f"26.3.0$(touch {marker})",
53+
"../escape",
54+
):
55+
with self.subTest(payload=payload):
56+
result = self.make("deploy", f"VERSION={payload}")
57+
self.assertNotEqual(result.returncode, 0)
58+
self.assertFalse(marker.exists())
59+
60+
def test_rejects_unsafe_tag_before_building(self):
61+
marker = self.site / "executed"
62+
tag = f"v26.3.0$(shell touch {marker})"
63+
for target, variable in (("build", f"TAG={tag}"), ("_build-tag", f"T={tag}")):
64+
with self.subTest(target=target):
65+
result = subprocess.run(
66+
["make", target, variable, f"FE_SRC={self.site}"],
67+
cwd=self.site,
68+
capture_output=True,
69+
text=True,
70+
check=False,
71+
)
72+
self.assertNotEqual(result.returncode, 0)
73+
self.assertFalse(marker.exists())
74+
75+
76+
if __name__ == "__main__":
77+
unittest.main()

0 commit comments

Comments
 (0)