diff --git a/.devcontainer/post-create.sh b/.devcontainer/post-create.sh index 3ca05fe..5171bf5 100644 --- a/.devcontainer/post-create.sh +++ b/.devcontainer/post-create.sh @@ -2,6 +2,6 @@ set -euo pipefail -version=0.10.0 +version=0.10.1 npm install -g "cowel@${version}" diff --git a/.github/skills/cowel-version-upgrade/SKILL.md b/.github/skills/cowel-version-upgrade/SKILL.md new file mode 100644 index 0000000..566e47f --- /dev/null +++ b/.github/skills/cowel-version-upgrade/SKILL.md @@ -0,0 +1,51 @@ +--- +name: cowel-version-upgrade +description: 'Upgrade COWEL paper sources and repo tooling to a newer COWEL release. Use when bumping : cowel version lines in src/*.cow, updating scripts and GitHub workflows, rebuilding docs, and verifying bitwise-identical outputs.' +argument-hint: ' [--dry-run]' +user-invocable: true +--- + +# COWEL Version Upgrade + +Upgrade this repository from one COWEL version to another in a repeatable, low-risk way. + +## When To Use +- Bumping COWEL from one release to another (for example 0.10.0 to 0.10.1) +- Updating paper headers in `src/*.cow` +- Updating workflow and script pins for COWEL +- Rebuilding docs and checking for bitwise-identical output + +## Inputs +- Old version (currently in sources), for example `0.10.0` +- New version (target), for example `0.10.1` +- Optional `--dry-run` to preview changed files + +## Procedure +1. Run version replacement: + - [upgrade-cowel-version.sh](./scripts/upgrade-cowel-version.sh) +2. Rebuild and verify: + - [rebuild-and-verify.sh](./scripts/rebuild-and-verify.sh) +3. If verification fails, patch only impactful nested inline-code rendering sites (for example switching selected `tcode` to `ocode`) and rerun verification. + +## Decision Points +- If only source headers changed and verify passes: no content-level patching required. +- If verify fails with nested-highlighting artifacts in generated HTML: update only the specific nested inline-code call sites that affect output. +- If a file should intentionally remain on an older COWEL syntax version: do not force-upgrade it; keep versioned legacy files unchanged unless explicitly requested. + +## Files Typically Touched +- `src/*.cow`: version header lines like `\: cowel X.Y.Z` +- `scripts/rebuild-docs.sh`: version comments/grep patterns +- `.github/workflows/*.yml`: pinned `cowel@X.Y.Z` +- `README.md`: documented version pin(s) +- `.devcontainer/post-create.sh`: devcontainer COWEL version pin +- Optional repo-specific setup docs (for example `.github/copilot-instructions.md`) + +## Completion Criteria +- No remaining old-version references: + - `rg -n "|cowel@|\\: cowel "` +- Rebuild succeeds for targeted docs. +- Verification passes with no mismatches. + +## Notes +- Keep changes minimal and targeted. +- Prefer surgical source edits over broad style changes when restoring bitwise output compatibility. diff --git a/.github/skills/cowel-version-upgrade/scripts/rebuild-and-verify.sh b/.github/skills/cowel-version-upgrade/scripts/rebuild-and-verify.sh new file mode 100755 index 0000000..4eab743 --- /dev/null +++ b/.github/skills/cowel-version-upgrade/scripts/rebuild-and-verify.sh @@ -0,0 +1,24 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Rebuild docs for current versioned sources, then verify generated output. +# Usage: +# ./scripts/rebuild-and-verify.sh + +repo_root="$(cd "$(dirname "$0")/../../../.." && pwd)" +cd "$repo_root" + +if [[ ! -x scripts/rebuild-docs.sh ]]; then + echo "Missing executable scripts/rebuild-docs.sh" >&2 + exit 1 +fi + +if [[ ! -x scripts/verify-docs.sh ]]; then + echo "Missing executable scripts/verify-docs.sh" >&2 + exit 1 +fi + +./scripts/rebuild-docs.sh +./scripts/verify-docs.sh + +echo "Rebuild + verify completed successfully." diff --git a/.github/skills/cowel-version-upgrade/scripts/upgrade-cowel-version.sh b/.github/skills/cowel-version-upgrade/scripts/upgrade-cowel-version.sh new file mode 100755 index 0000000..40a6188 --- /dev/null +++ b/.github/skills/cowel-version-upgrade/scripts/upgrade-cowel-version.sh @@ -0,0 +1,66 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Bulk-upgrade repo references from one COWEL version to another. +# Usage: +# ./scripts/upgrade-cowel-version.sh [--dry-run] + +if [[ $# -lt 2 || $# -gt 3 ]]; then + echo "Usage: $0 [--dry-run]" >&2 + exit 2 +fi + +old="$1" +new="$2" +dry_run="${3:-}" + +repo_root="$(cd "$(dirname "$0")/../../../.." && pwd)" +cd "$repo_root" + +if [[ "$old" == "$new" ]]; then + echo "Old and new versions are identical: $old" >&2 + exit 2 +fi + +# Update only files that are expected to contain version pins. +mapfile -t files < <( + { + find src -type f -name '*.cow' -print + printf '%s\n' README.md scripts/rebuild-docs.sh + find .github/workflows -type f \( -name '*.yml' -o -name '*.yaml' \) -print + printf '%s\n' .devcontainer/post-create.sh + [[ -f .github/copilot-instructions.md ]] && printf '%s\n' .github/copilot-instructions.md + } | sort -u +) + +changed=0 +for f in "${files[@]}"; do + [[ -f "$f" ]] || continue + + if [[ -n "$dry_run" ]]; then + if rg -q "${old}|cowel@${old}|\\\\: cowel ${old}" "$f"; then + echo "WOULD UPDATE: $f" + changed=1 + fi + continue + fi + + if rg -q "${old}|cowel@${old}|\\\\: cowel ${old}" "$f"; then + sed -i "s/${old//./\\.}/${new}/g" "$f" + echo "UPDATED: $f" + changed=1 + fi +done + +if [[ -n "$dry_run" ]]; then + if [[ $changed -eq 0 ]]; then + echo "No files would be updated for ${old} -> ${new}." + fi + exit 0 +fi + +if [[ $changed -eq 0 ]]; then + echo "No files updated for ${old} -> ${new}." +else + echo "Version upgrade applied: ${old} -> ${new}." +fi diff --git a/.github/workflows/verify-docs.yml b/.github/workflows/verify-docs.yml index 01000f8..9e7693d 100644 --- a/.github/workflows/verify-docs.yml +++ b/.github/workflows/verify-docs.yml @@ -15,7 +15,7 @@ jobs: uses: actions/checkout@v4 - name: Install cowel - run: npm install -g cowel@0.10.0 + run: npm install -g cowel@0.10.1 - name: Verify docs match sources run: bash scripts/verify-docs.sh diff --git a/README.md b/README.md index 746c4d4..b51e624 100644 --- a/README.md +++ b/README.md @@ -10,5 +10,5 @@ or if you have suggestions for improvement. This repository includes a GitHub Codespaces/devcontainer setup that installs Node.js, -`cowel@0.10.0`, +`cowel@0.10.1`, and the COWEL VS Code extension automatically. diff --git a/scripts/rebuild-docs.sh b/scripts/rebuild-docs.sh index 544f8f8..0d0fc3c 100755 --- a/scripts/rebuild-docs.sh +++ b/scripts/rebuild-docs.sh @@ -1,5 +1,5 @@ #!/usr/bin/env bash -# Rebuild HTML files in docs/ for every COWEL 0.10.0 source file, +# Rebuild HTML files in docs/ for every COWEL 0.10.1 source file, # but only when a corresponding HTML file already exists in docs/. # # Usage: scripts/rebuild-docs.sh @@ -18,6 +18,6 @@ while IFS= read -r src; do fi cowel run "$src" "$dest" echo "BUILT: $src -> $dest" -done < <(grep -rl '\\: cowel 0\.10\.0' src/) +done < <(grep -rl '\\: cowel 0\.10\.1' src/) exit $failed diff --git a/src/array.cow b/src/array.cow index e6343e7..4354357 100644 --- a/src/array.cow +++ b/src/array.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title = {\tcode{std::array} is a wrapper for an array!}){ diff --git a/src/ascii.cow b/src/ascii.cow index 99c831d..2958fdf 100644 --- a/src/ascii.cow +++ b/src/ascii.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow")\ \ \cowel_macro("charset"){\tt{\hl("string"){[\cowel_put]}}}\ diff --git a/src/better-shifting.cow b/src/better-shifting.cow index 3f9dd30..c0c266a 100644 --- a/src/better-shifting.cow +++ b/src/better-shifting.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Better shifting}){ diff --git a/src/big-int.cow b/src/big-int.cow index 794bb7d..0d29a7d 100644 --- a/src/big-int.cow +++ b/src/big-int.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={\tcode{std::big_int}}){ diff --git a/src/bit-cast-padding.cow b/src/bit-cast-padding.cow index 71a7846..9d5f4dd 100644 --- a/src/bit-cast-padding.cow +++ b/src/bit-cast-padding.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Fixing \tcode{std::bit_cast} of types\br{}with padding bits}){ diff --git a/src/bit-permutations-simd.cow b/src/bit-permutations-simd.cow index ba0b37c..e63b971 100644 --- a/src/bit-permutations-simd.cow +++ b/src/bit-permutations-simd.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={\tcode{std::simd} overloads for bit permutations}){ diff --git a/src/bitint.cow b/src/bitint.cow index db1a48f..f9d4944 100644 --- a/src/bitint.cow +++ b/src/bitint.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Bit-precise integers}){ diff --git a/src/case-ranges.cow b/src/case-ranges.cow index 5ae87b9..b52d5d6 100644 --- a/src/case-ranges.cow +++ b/src/case-ranges.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Case ranges}){ diff --git a/src/charconv-ext.cow b/src/charconv-ext.cow index 2be03ec..3ea56da 100644 --- a/src/charconv-ext.cow +++ b/src/charconv-ext.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Extending \tcode{} support to more character types}){ diff --git a/src/clarify-fp-overflow.cow b/src/clarify-fp-overflow.cow index ff25346..f01a64f 100644 --- a/src/clarify-fp-overflow.cow +++ b/src/clarify-fp-overflow.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Clarify the behavior of floating-point overflow}){ diff --git a/src/clmul.cow b/src/clmul.cow index ac4b11b..4d6353f 100644 --- a/src/clmul.cow +++ b/src/clmul.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Carry-less product: \tt{std::clmul}}){ diff --git a/src/cmath-c23.cow b/src/cmath-c23.cow index 426a3d3..9b89c72 100644 --- a/src/cmath-c23.cow +++ b/src/cmath-c23.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Rebasing \tt{} on C23}){ diff --git a/src/concise-grammar.cow b/src/concise-grammar.cow index 856319d..195a98c 100644 --- a/src/concise-grammar.cow +++ b/src/concise-grammar.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Improve readability of the C++ grammar by adding a syntax for groups and repetitions}){ diff --git a/src/correctly-rounded-math.cow b/src/correctly-rounded-math.cow index 1d39af2..532fb9e 100644 --- a/src/correctly-rounded-math.cow +++ b/src/correctly-rounded-math.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Correctly rounded floating-point maths functions}){ diff --git a/src/deprecate-unicode-conversion.cow b/src/deprecate-unicode-conversion.cow index 1469804..e94cd54 100644 --- a/src/deprecate-unicode-conversion.cow +++ b/src/deprecate-unicode-conversion.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Deprecate implicit conversions diff --git a/src/fix-declaration-font.cow b/src/fix-declaration-font.cow index 0ddb936..d73cf2f 100644 --- a/src/fix-declaration-font.cow +++ b/src/fix-declaration-font.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Fix inappropriate font choices for "declaration"}){ diff --git a/src/fix-floating-from-chars.cow b/src/fix-floating-from-chars.cow index 41b913c..b9b11b4 100644 --- a/src/fix-floating-from-chars.cow +++ b/src/fix-floating-from-chars.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Fix defects in floating-point \tcode{std::from_chars}\br diff --git a/src/floating-point-values.cow b/src/floating-point-values.cow index b1c45ab..9adb88f 100644 --- a/src/floating-point-values.cow +++ b/src/floating-point-values.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Values of floating-point types}){ diff --git a/src/intdiv.cow b/src/intdiv.cow index 8d97f0c..61a2c67 100644 --- a/src/intdiv.cow +++ b/src/intdiv.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Integer division}){ diff --git a/src/libwg21-9.cow b/src/libwg21-9.cow index cab9fbf..92bd57e 100644 --- a/src/libwg21-9.cow +++ b/src/libwg21-9.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_actions{ \cowel_macro("hl"){\cowel_paragraph_enter\cowel_highlight_as(...){\cowel_put}} diff --git a/src/more-bitset-operations.cow b/src/more-bitset-operations.cow index b4683f7..85d6750 100644 --- a/src/more-bitset-operations.cow +++ b/src/more-bitset-operations.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={More bitset operations}){ diff --git a/src/more-trailing-commas.cow b/src/more-trailing-commas.cow index a9888b2..ff51818 100644 --- a/src/more-trailing-commas.cow +++ b/src/more-trailing-commas.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={More trailing commas}){ diff --git a/src/more-unicode-escapes.cow b/src/more-unicode-escapes.cow index 9e0a653..7239dbc 100644 --- a/src/more-unicode-escapes.cow +++ b/src/more-unicode-escapes.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \cowel_macro("zwnbsp"){\'ZERO WIDTH NO-BREAK SPACE'} diff --git a/src/n-algorithms.cow b/src/n-algorithms.cow index 6087c7f..08e11a7 100644 --- a/src/n-algorithms.cow +++ b/src/n-algorithms.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={\tcode{partial_sort_at_most}, \tcode{nth_element_at_most}}){ diff --git a/src/named-args.cow b/src/named-args.cow index 831fe4b..5fcbf10 100644 --- a/src/named-args.cow +++ b/src/named-args.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Named function arguments}){ diff --git a/src/random-chars.cow b/src/random-chars.cow index 125ee10..0839f38 100644 --- a/src/random-chars.cow +++ b/src/random-chars.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Supporting \tt{signed char} and \tt{unsigned char}\br in random number generation}){ diff --git a/src/rename-sat.cow b/src/rename-sat.cow index 4cfdc31..7dbc380 100644 --- a/src/rename-sat.cow +++ b/src/rename-sat.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Renaming saturation arithmetic functions}){ diff --git a/src/replace-charconv.cow b/src/replace-charconv.cow index b12046f..2d136ae 100644 --- a/src/replace-charconv.cow +++ b/src/replace-charconv.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Provide a better replacement for \tt{std::to_chars} and \tt{std::from_chars}}){ diff --git a/src/sd-7-updates.cow b/src/sd-7-updates.cow index 3186b8a..f2a58b5 100644 --- a/src/sd-7-updates.cow +++ b/src/sd-7-updates.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \cowel_macro("bolden"){\del{\cowel_put} \ins{\b{\cowel_put}}} diff --git a/src/sequential-hex-digits.cow b/src/sequential-hex-digits.cow index 24c8cb8..4459b80 100644 --- a/src/sequential-hex-digits.cow +++ b/src/sequential-hex-digits.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Sequential hexadecimal digits}){ diff --git a/src/template-9.cow b/src/template-9.cow index 40638fc..836c06b 100644 --- a/src/template-9.cow +++ b/src/template-9.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head( diff --git a/src/to-signed-unsigned.cow b/src/to-signed-unsigned.cow index cca859c..c3d58d0 100644 --- a/src/to-signed-unsigned.cow +++ b/src/to-signed-unsigned.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={\tcode{std::to_signed} and \tcode{std::to_unsigned}}){ diff --git a/src/trivially-copyable-optional-ref.cow b/src/trivially-copyable-optional-ref.cow index c00b670..c48503a 100644 --- a/src/trivially-copyable-optional-ref.cow +++ b/src/trivially-copyable-optional-ref.cow @@ -1,4 +1,4 @@ -\: cowel 0.10.0 +\: cowel 0.10.1 \cowel_include("libwg21-9.cow") \wg21_head(title={Make \tcode{optional} trivially copyable\br{}(NB comment US 134-215)}){