From 2fe0ffbeb2653377aae2a4054096ffae09f273cf Mon Sep 17 00:00:00 2001 From: HermanPeeren Date: Sun, 15 Nov 2026 10:44:15 +0100 Subject: [PATCH] Put the version in the names of the release files The release files are now joomla-ws-api-.json, .yaml, .html and .sha256. The README explains how to find the latest release with the GitHub API. The routes job of CI gets the fixed name "Routes", so it can be a required status check for main. --- .github/workflows/ci.yml | 3 ++- .github/workflows/release.yml | 10 +++++----- README.md | 22 +++++++++++++++------- scripts/build.mjs | 24 +++++++++++++----------- 4 files changed, 35 insertions(+), 24 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index de080b7..c717c3c 100644 --- a/.github/workflows/ci.yml +++ b/.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: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3831768..9b65470 100644 --- a/.github/workflows/release.yml +++ b/.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-.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 \ diff --git a/README.md b/README.md index bd58e12..dae345c 100644 --- a/README.md +++ b/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//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//joomla-ws-api-.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-.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 diff --git a/scripts/build.mjs b/scripts/build.mjs index d3edd3f..b8241c3 100644 --- a/scripts/build.mjs +++ b/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-.json the spec, unchanged +// joomla-ws-api-.yaml the same spec in YAML +// joomla-ws-api-.html readable documentation (Redoc) +// joomla-ws-api-.sha256 checksums of the files above // // Usage: node scripts/build.mjs [--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`);