From 1863a172378e06b4f3ec37cc169b635ff663db25 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 16:55:02 +0100 Subject: [PATCH 1/4] fix(scripts): repoint README.md references at README.adoc The .md -> .adoc migration moved README.md to README.adoc but left every script reading the old name. Affected release/scripts/package.sh, release/scripts/version.sh and scripts/ci/package.sh. Note the variable-prefixed forms - "$PROJECT_ROOT/README.md", "${ROOT_DIR}/README.md" - which a token-boundary rewrite misses. Two of these are 'cp'/'sed -i' operations guarded by '2>/dev/null || true', so they have been failing silently: the packaged artefact simply had no README, and the version bump silently stopped rewriting the badge line. Found by an estate-wide sweep of 454 repos: 56 such checks across 18 repos. Same class as hyperpolymath/Axiom.jl#82. --- cli/examples/setup-project.sh | 2 +- release/scripts/package.sh | 2 +- release/scripts/version.sh | 8 ++++---- release/verify/verify_release.sh | 2 +- scripts/ci/package.sh | 4 ++-- scripts/ci/test-integration.sh | 2 +- 6 files changed, 10 insertions(+), 10 deletions(-) diff --git a/cli/examples/setup-project.sh b/cli/examples/setup-project.sh index a8c68c8b..72b03a05 100755 --- a/cli/examples/setup-project.sh +++ b/cli/examples/setup-project.sh @@ -90,4 +90,4 @@ echo " 3. Sync with Moodle: aws sync --download" echo " 4. Batch mark: aws batch ./submissions" echo "" echo "For help: aws --help" -echo "Documentation: cat README.md" +echo "Documentation: cat README.adoc" diff --git a/release/scripts/package.sh b/release/scripts/package.sh index 39c0633f..a7a59156 100755 --- a/release/scripts/package.sh +++ b/release/scripts/package.sh @@ -156,7 +156,7 @@ build_deb() { fi # Copy documentation - cp "$PROJECT_ROOT/README.md" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true + cp "$PROJECT_ROOT/README.adoc" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true cp "$PROJECT_ROOT/LICENSE" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true # Build package diff --git a/release/scripts/version.sh b/release/scripts/version.sh index 24f12f52..bf449c4e 100755 --- a/release/scripts/version.sh +++ b/release/scripts/version.sh @@ -154,11 +154,11 @@ update_python_version() { update_documentation() { local version=$1 - # Update README.md - if [ -f "$PROJECT_ROOT/README.md" ]; then + # Update README.adoc + if [ -f "$PROJECT_ROOT/README.adoc" ]; then # Update badge version if exists - sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.md" 2>/dev/null || true - log_success "Updated README.md" + sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.adoc" 2>/dev/null || true + log_success "Updated README.adoc" fi # Update CLAUDE.md diff --git a/release/verify/verify_release.sh b/release/verify/verify_release.sh index d5f6a076..bbaf1cf2 100755 --- a/release/verify/verify_release.sh +++ b/release/verify/verify_release.sh @@ -154,7 +154,7 @@ check_archive_contents() { # Check for essential files local essential_files=( - "README.md" + "README.adoc" "LICENSE" ) diff --git a/scripts/ci/package.sh b/scripts/ci/package.sh index 4b3e2216..9532f37c 100755 --- a/scripts/ci/package.sh +++ b/scripts/ci/package.sh @@ -79,8 +79,8 @@ package_deb() { fi # Copy documentation - if [ -f "${ROOT_DIR}/README.md" ]; then - cp "${ROOT_DIR}/README.md" "${deb_dir}/usr/share/doc/${package_name}/" + if [ -f "${ROOT_DIR}/README.adoc" ]; then + cp "${ROOT_DIR}/README.adoc" "${deb_dir}/usr/share/doc/${package_name}/" fi if [ -f "${ROOT_DIR}/LICENSE" ]; then diff --git a/scripts/ci/test-integration.sh b/scripts/ci/test-integration.sh index 1ba9c95d..ad053bfe 100755 --- a/scripts/ci/test-integration.sh +++ b/scripts/ci/test-integration.sh @@ -226,7 +226,7 @@ test_configuration_files() { test_documentation() { log_info "Testing documentation..." - local required_docs=("README.md" "CLAUDE.md") + local required_docs=("README.adoc" "CLAUDE.md") for doc in "${required_docs[@]}"; do if [ ! -f "${ROOT_DIR}/${doc}" ]; then From ca05a0a83414cf48d0ab1b88ba31a55bb201954a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:17:39 +0100 Subject: [PATCH 2/4] Update release/scripts/package.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- release/scripts/package.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/release/scripts/package.sh b/release/scripts/package.sh index a7a59156..25fa53bf 100755 --- a/release/scripts/package.sh +++ b/release/scripts/package.sh @@ -156,7 +156,7 @@ build_deb() { fi # Copy documentation - cp "$PROJECT_ROOT/README.adoc" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true + cp "$PROJECT_ROOT/README.adoc" "${pkg_dir}/usr/share/doc/${pkg_name}/" cp "$PROJECT_ROOT/LICENSE" "${pkg_dir}/usr/share/doc/${pkg_name}/" 2>/dev/null || true # Build package From c88027a993bd7f1ed36a8392cacf8472b207540a Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 17:17:51 +0100 Subject: [PATCH 3/4] Update scripts/ci/package.sh Co-authored-by: codacy-production[bot] <61871480+codacy-production[bot]@users.noreply.github.com> Signed-off-by: Jonathan D.A. Jewell <6759885+hyperpolymath@users.noreply.github.com> --- scripts/ci/package.sh | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/scripts/ci/package.sh b/scripts/ci/package.sh index 9532f37c..032e18a4 100755 --- a/scripts/ci/package.sh +++ b/scripts/ci/package.sh @@ -79,9 +79,7 @@ package_deb() { fi # Copy documentation - if [ -f "${ROOT_DIR}/README.adoc" ]; then - cp "${ROOT_DIR}/README.adoc" "${deb_dir}/usr/share/doc/${package_name}/" - fi + cp "${ROOT_DIR}/README.adoc" "${deb_dir}/usr/share/doc/${package_name}/" if [ -f "${ROOT_DIR}/LICENSE" ]; then cp "${ROOT_DIR}/LICENSE" "${deb_dir}/usr/share/doc/${package_name}/" From 3285a3e45f42b210f04cae04fc4606595c40ab0b Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Wed, 26 Aug 2026 18:09:49 +0100 Subject: [PATCH 4/4] fix(release): do not mask a failed version-badge update 'sed -i ... README.adoc 2>/dev/null || true' swallowed any failure, then unconditionally logged 'Updated README.adoc'. A release could therefore ship advertising the previous version with nothing to surface it -- the log actively asserted success that had not happened. Now fails loudly. Two other findings on this PR were checked and NOT actioned, with reasons: * 'the regex may incorrectly update other version badges (node, dependencies)' -- README.adoc contains exactly ONE 'version-' badge, the project's own (version-0.1.0-blue). The others are License-MPL_2.0, build-passing, OpenSSF and Idris-Inside; none matches 'version-[0-9.]*-'. No collision exists to guard against. * 'README.adoc ... using 2>/dev/null || true masks potential failures' -- README.adoc's copy at package.sh:159 has NO masking. The '|| true' is on line 160, the LICENSE copy. The finding misread which line it was describing. Co-Authored-By: Claude Opus 5 --- release/scripts/version.sh | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/release/scripts/version.sh b/release/scripts/version.sh index bf449c4e..0f20251e 100755 --- a/release/scripts/version.sh +++ b/release/scripts/version.sh @@ -157,8 +157,14 @@ update_documentation() { # Update README.adoc if [ -f "$PROJECT_ROOT/README.adoc" ]; then # Update badge version if exists - sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.adoc" 2>/dev/null || true - log_success "Updated README.adoc" + # Do NOT mask this: a silently-failed badge update ships a release + # advertising the wrong version, and nothing surfaces it. + if sed -i "s/version-[0-9.]*-/version-$version-/" "$PROJECT_ROOT/README.adoc"; then + log_success "Updated README.adoc" + else + log_error "Failed to update the version badge in README.adoc" + exit 1 + fi fi # Update CLAUDE.md