Put the version in the names of the release files

.github/workflows/ci.yml

@@ -64,7 +64,8 @@ jobs:
           retention-days: 14
 
   routes:
-    name: Routes of Joomla ${{ needs.validate.outputs.minor }}
+    # A fixed name: it is a required status check for main.
+    name: Routes
     needs: validate
     runs-on: ubuntu-latest
     steps:

.github/workflows/release.yml

@@ -2,9 +2,9 @@ name: Release
 
 # Push a tag that equals info.version of src/joomla-ws-api.json, for instance 6.2.1:
 #   git tag -a 6.2.1 -m "Joomla Web Services API 6.2.1" && git push origin 6.2.1
-# The release gets the files joomla-ws-api.json, joomla-ws-api.yaml, index.html and SHA256SUMS.
-# The highest version becomes the "latest" release, so this URL always gives the newest spec:
-#   https://github.com/joomla-projects/API-Endpoints/releases/latest/download/joomla-ws-api.json
+# The release gets the files joomla-ws-api-<version>.json, .yaml, .html and .sha256.
+# The highest version becomes the "latest" release:
+#   https://api.github.com/repos/joomla-projects/API-Endpoints/releases/latest
 
 on:
   push:
@@ -45,7 +45,7 @@ jobs:
           ' CHANGELOG.md > notes.md
           {
             echo
-            echo "Download: [joomla-ws-api.json](https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/joomla-ws-api.json)"
+            echo "Download: [joomla-ws-api-${GITHUB_REF_NAME}.json](https://github.com/${GITHUB_REPOSITORY}/releases/download/${GITHUB_REF_NAME}/joomla-ws-api-${GITHUB_REF_NAME}.json)"
           } >> notes.md
           cat notes.md
 
@@ -57,7 +57,7 @@ jobs:
             | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' | sort -V | tail -n 1)
           latest=false
           [ "$highest" = "$GITHUB_REF_NAME" ] && latest=true
-          gh release create "$GITHUB_REF_NAME" dist/joomla-ws-api.json dist/joomla-ws-api.yaml dist/index.html dist/SHA256SUMS \
+          gh release create "$GITHUB_REF_NAME" dist/* \
             --verify-tag \
             --title "Joomla Web Services API $GITHUB_REF_NAME" \
             --notes-file notes.md \

README.md

@@ -10,21 +10,29 @@ The specification is one file: [`src/joomla-ws-api.json`](src/joomla-ws-api.json
 
 | What | URL |
 | --- | --- |
-| Latest release | https://github.com/joomla-projects/API-Endpoints/releases/latest/download/joomla-ws-api.json |
-| Latest release, YAML | https://github.com/joomla-projects/API-Endpoints/releases/latest/download/joomla-ws-api.yaml |
-| A specific release | `https://github.com/joomla-projects/API-Endpoints/releases/download/<version>/joomla-ws-api.json` |
-| Release information (JSON) | https://api.github.com/repos/joomla-projects/API-Endpoints/releases/latest |
+| Latest release (web page) | https://github.com/joomla-projects/API-Endpoints/releases/latest |
+| Latest release (JSON, for tools and agents) | https://api.github.com/repos/joomla-projects/API-Endpoints/releases/latest |
+| A specific release | `https://github.com/joomla-projects/API-Endpoints/releases/download/<version>/joomla-ws-api-<version>.json` |
 | Not yet released (`main`) | https://raw.githubusercontent.com/joomla-projects/API-Endpoints/main/src/joomla-ws-api.json |
 
-For AI agents and other tools, use the first URL: it always gives the newest release. Each release also has an
-`index.html` with readable documentation (Redoc) and a `SHA256SUMS` file.
+Each release has these files, with its version in the name: `joomla-ws-api-<version>.json`, the same spec in
+YAML (`.yaml`), readable documentation (`.html`, Redoc) and checksums (`.sha256`).
+
+For AI agents and other tools: the JSON of the latest release has the version in `tag_name`, and the download
+URL of each file in `assets[].browser_download_url`. For instance:
+
+```bash
+curl -s https://api.github.com/repos/joomla-projects/API-Endpoints/releases/latest \
+  | jq -r '.assets[] | select(.name | endswith(".json")) | .browser_download_url'
+```
 
 ## Versions
 
 A release has the version of the Joomla minor version it describes: release **6.2**.x is the API of
 Joomla **6.2**. Patch releases (6.2.1, 6.2.2, ...) improve the description of the same API. When Joomla's web
 services change in a new minor version, the specification gets a release with that minor version.
-The version is in `info.version` of the spec and in the release tag, never in the file name.
+The version is in `info.version` of the spec, in the release tag and in the names of the release files; the
+source file in this repository is always `src/joomla-ws-api.json`.
 See [CHANGELOG.md](CHANGELOG.md).
 
 ## Documentation

scripts/build.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-// Builds the release files in dist/:
-//   joomla-ws-api.json   the spec, unchanged
-//   joomla-ws-api.yaml   the same spec in YAML
-//   index.html           readable documentation (Redoc)
-//   SHA256SUMS           checksums of the files above
+// Builds the release files in dist/, with the version of the spec in each file name:
+//   joomla-ws-api-<version>.json     the spec, unchanged
+//   joomla-ws-api-<version>.yaml     the same spec in YAML
+//   joomla-ws-api-<version>.html     readable documentation (Redoc)
+//   joomla-ws-api-<version>.sha256   checksums of the files above
 //
 // Usage: node scripts/build.mjs [--tag <tag>]
 //   --tag: fail unless the tag equals info.version of the spec (used by the release workflow).
@@ -34,14 +34,16 @@ const redocly = (...a) => {
   execFileSync(process.execPath, [path.join('node_modules', '@redocly', 'cli', 'bin', 'cli.js'), ...a], { stdio: 'inherit' });
 };
 
+const base = `joomla-ws-api-${version}`;
+const files = [`${base}.json`, `${base}.yaml`, `${base}.html`];
+
 // The spec is one self-contained file: the release JSON is the source file as it is.
-fs.copyFileSync(SRC, `${DIST}/joomla-ws-api.json`);
-redocly('bundle', SRC, '--output', `${DIST}/joomla-ws-api.yaml`);
-redocly('build-docs', SRC, '--output', `${DIST}/index.html`, '--title', `Joomla ${version} Web Services API`);
+fs.copyFileSync(SRC, `${DIST}/${base}.json`);
+redocly('bundle', SRC, '--output', `${DIST}/${base}.yaml`);
+redocly('build-docs', SRC, '--output', `${DIST}/${base}.html`, '--title', `Joomla ${version} Web Services API`);
 
-const files = ['joomla-ws-api.json', 'joomla-ws-api.yaml', 'index.html'];
 const sums = files.map((f) => `${crypto.createHash('sha256').update(fs.readFileSync(path.join(DIST, f))).digest('hex')}  ${f}`);
-fs.writeFileSync(`${DIST}/SHA256SUMS`, sums.join('\n') + '\n');
+fs.writeFileSync(`${DIST}/${base}.sha256`, sums.join('\n') + '\n');
 
 console.log(`\nBuilt Joomla Web Services API ${version} in ${DIST}/:`);
-for (const f of [...files, 'SHA256SUMS']) console.log(`  ${f}  ${(fs.statSync(path.join(DIST, f)).size / 1024).toFixed(0)} KB`);
+for (const f of [...files, `${base}.sha256`]) console.log(`  ${f}  ${(fs.statSync(path.join(DIST, f)).size / 1024).toFixed(0)} KB`);