Skip to content

v1.0.5 — GitHub Pages deployment for benchmark results, documentation, and release bump

Choose a tag to compare

View all tags
@tobrien tobrien released this 31 Dec 06:35
· 1 commit to working since this release
v1.0.5
40cc2a0
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Summary

This release (v1.0.5) adds automatic GitHub Pages deployment to the AsyncLocalStorage benchmark workflow and ships comprehensive documentation and support material for the deployment. The package version was bumped to 1.0.5 (removing the prior -dev pre-release suffix). The change set is focused on CI/infra and documentation — there are no functional API changes to benchmark code.

Highlights

  • CI: Added GitHub Pages permissions and a new deploy-to-pages job to .github/workflows/benchmark.yml. The job packages generated reports and deploys them to GitHub Pages using official actions.
  • Documentation: Added a set of user-facing docs and guides to support the Pages deployment and to describe the site and artifacts (CHANGES_MADE.md, DEPLOYMENT_SUMMARY.md, GITHUB_PAGES_SETUP.md, QUICK_START.md, docs/README.md, and a deployment diagram DEPLOYMENT_DIAGRAM.txt).
  • Packaging: package.json version updated from 1.0.4 → 1.0.5.

Total size of this change set: 9 files changed, 1529 insertions, 3 deletions.

What changed (technical details)

  1. Workflow changes (.github/workflows/benchmark.yml)
  • New permissions added at the top-level:
    • pages: write
    • id-token: write
      (Existing permissions for contents: write and actions: read remain.)
  • New job deploy-to-pages (runs after compare-versions):
    • Only runs on main (condition: always() && github.ref == 'refs/heads/main').
    • Downloads the version-comparison artifact created by the compare-versions job.
    • Installs Node.js (20.x) and project dependencies (npm ci).
    • Prepares GH Pages content in a gh-pages/ directory by:
      • copying pages-assets/docs (downloaded artifact) or the local docs/ directory if present;
      • creating a fallback index.html when no docs exist (simple landing page with generation timestamp);
      • copying result data to gh-pages/results/ if present;
      • generating a styles.css file if missing.
    • Uploads an artifact using actions/upload-pages-artifact@v3 and deploys with actions/deploy-pages@v4.
  • deploy-to-pages uses continue-on-error for artifact download to tolerate missing artifacts and contains logic to provide useful fallbacks.

Notes about the workflow logic and behavior:

  • The job is wired with needs: [compare-versions] and if: always() — this means it will run after the compare-versions job completes regardless of success/failure, but only when the run is against the main branch. The deploy step therefore explicitly contains fallback behavior to avoid publishing an empty or broken site when artifacts are missing.
  • Release creation remains in the workflow (create-release) and still uploads a compressed benchmark-results.tar.gz archive. The release job uses actions/create-release@v1 and actions/upload-release-asset@v1 with GITHUB_TOKEN.
  1. Documentation and supporting files (new files)
  • CHANGES_MADE.md — detailed explanation of what was added.
  • DEPLOYMENT_SUMMARY.md — implementation summary and file layout.
  • GITHUB_PAGES_SETUP.md — step-by-step enablement and troubleshooting guide for GitHub Pages.
  • QUICK_START.md — short 3-step instructions to enable and trigger a deploy.
  • docs/README.md — overview of the docs directory and generated reports.
  • DEPLOYMENT_DIAGRAM.txt — ASCII architecture and flow diagram.
  1. package.json
  • Version bumped to 1.0.5.
  • No new runtime dependencies were added; scripts remain the same and contain the comparison and report-generation commands used by the workflow (compare-versions, generate-report, multi-iteration, etc.).

Why this change (motivation)

  • The core benchmarking workflow already generated per-version results and compare-versions output. This change provides a fully automated public-facing way to view and preserve those results via GitHub Pages, making benchmark outputs discoverable and shareable without manual packaging or external hosting.
  • The documentation bundle was added to make enabling and maintaining Pages straightforward and to document the CI flow and fallback behavior.
  • The version bump (1.0.5) finalizes the prior -dev release candidate and aligns package metadata with the published release.

Files added / modified (high level)

  • Modified: .github/workflows/benchmark.yml (added permissions + 173-line deploy job)
  • Added documentation: CHANGES_MADE.md, DEPLOYMENT_SUMMARY.md, GITHUB_PAGES_SETUP.md, QUICK_START.md, docs/README.md, DEPLOYMENT_DIAGRAM.txt
  • Modified: package.json (version: 1.0.5)

Top changed files (by lines added):

  • GITHUB_PAGES_SETUP.md (~319 lines)
  • DEPLOYMENT_SUMMARY.md (~312 lines)
  • DEPLOYMENT_DIAGRAM.txt (~215 lines)
  • CHANGES_MADE.md (~265 lines)
  • docs/README.md (~143 lines)
  • QUICK_START.md (~100 lines)
  • .github/workflows/benchmark.yml (deploy job ~173 lines)

Total changes: 9 files changed, 1529 insertions, 3 deletions.

User and developer implications

For repository maintainers / CI operators

  • Required: enable GitHub Pages in repository Settings → Pages and select "GitHub Actions" as the source (instructions are provided in GITHUB_PAGES_SETUP.md and QUICK_START.md). Without enabling Pages the deploy job will succeed but the site will not be published.
  • The workflow now requires additional permissions for Pages deployment. The pages: write and id-token: write permissions broaden the workflow's ability to deploy; verify that these are acceptable under your security policy.
  • The deploy-to-pages job uses the version-comparison artifact from compare-versions. If that artifact is missing (compare-versions failed or artifact upload failed), the deploy job will attempt to use local docs/ content or create a fallback index.html to avoid publishing an empty site. Expect placeholder pages if the pipeline could not generate reports.
  • Artifact retention and release packaging: artifacts uploaded in the workflow use a 30-day retention policy. The created release includes a benchmark-results.tar.gz archive for raw data; the Pages deployment publishes the HTML/JSON reports.

For consumers (site visitors)

  • A new public site will be available at the Pages URL once enabled (example: https://tobrien.github.io/als-benchmark-basic/). It contains the landing page, interactive version comparison, JSON data files (version-comparison.json, performance-report.json, performance-summary.json), and raw results under results/.

For developers working on the benchmark code

  • No source/API changes were made to benchmark scripts or library behavior in this release. There are no breaking changes to the benchmarking scripts or their command-line usage.
  • The package.json engines.node remains >=16.0.0; the workflow uses Node.js 20.x to build reports and deploy pages.

Backwards-compatibility and breaking changes

  • Automated analysis (and manual review of the change set) found no obvious breaking changes to code-level APIs or benchmark scripts. The release is primarily CI and documentation additions.
  • The only change to package metadata is the version bump from 1.0.4 to 1.0.5.
  • The only behavioural change that maintainers should be aware of is CI behavior: the workflow now publishes results to GitHub Pages. This is a repository-level configuration change (Pages permission + enabling Pages in repository settings) rather than a code-level API change.

Risk assessment and operational notes

  1. Permissions and security
  • pages: write and id-token: write are required for actions/deploy-pages to publish the site. Confirm your organization’s policy for Actions permissions and OIDC usage.
  • The deploy flow uses the official GitHub Actions for Pages (upload-pages-artifact + deploy-pages), which follow the documented patterns for Pages deployment.
  1. Partial failures and fallbacks
  • deploy-to-pages uses if: always() with needs: [compare-versions], so it will attempt to run even if compare-versions fails. The job includes defensive logic:
    • If version-comparison artifact cannot be downloaded, the job tries the local docs/ directory.
    • If no docs or results exist, a minimal fallback index.html and styles.css are generated and published so a stable, informative page is served instead of an error page.
  • Consequence: maintainers may see placeholder content published if builds fail. Check the Actions run logs and the compare-versions output to ensure actual reports are generated.
  1. Artifact retention and release artifacts
  • Artifacts uploaded by the workflow (benchmark results and the version-comparison combination) use 30-day retention. If you need longer retention, adjust the workflow or archive artifacts elsewhere.
  • The create-release job still packages and uploads benchmark-results.tar.gz to GitHub Releases. The workflow message explicitly notes that full HTML documentation is generated during site build and may not be included in the release archive.
  1. CDN and client-side assets
  • The generated site’s reports reference Chart.js and other assets (per the docs). If those use CDNs, a consumer’s browser network access is required; check docs or adjust to bundle local assets if offline access is required.

How this release ties back to recent releases and project evolution

  • Release cadence: the project has used a pattern of development pre-release tags (e.g., v1.0.5-dev.0) and follow-up final release bumps. Prior tags/timeline show v1.0.4 and intermediate dev tags. This release finalizes the v1.0.5 packaging.
  • Focus evolution: earlier commits through August refactored the benchmark workflow and report generation, improving the reliability and structure of result handling. This release builds on that work by adding publishing and extensive documentation so that generated reports are visible and discoverable without manual steps.

How to use / verify (quick reference for maintainers)

  • Enable GitHub Pages in repository Settings → Pages and select "GitHub Actions" as the source.

  • Push the release branch (main) or run the workflow manually:

    • From the repository Actions tab: select "AsyncLocalStorage Benchmark" and click "Run workflow" (choose main and inputs as needed).
    • Or push to main: git add . && git commit -m "Add GitHub Pages deployment" && git push origin main

  • Watch the workflow run in Actions. Key jobs to watch:

    • benchmark (matrix of Node.js versions)
    • compare-versions (generates reports)
    • deploy-to-pages (creates and publishes the site)

  • Verify the published Pages site at the repository’s Pages URL after the deploy-to-pages job finishes.

  • To preview the generated docs locally: cd docs && python3 -m http.server 8000 and open http://localhost:8000

Notable implementation details (quick checklist)

  • Workflow: uses actions/checkout@v4, actions/setup-node@v4, actions/upload-pages-artifact@v3, actions/deploy-pages@v4, actions/upload-artifact@v4, actions/download-artifact@v4.
  • Fallback behavior ensures a meaningful page is published even when artifacts are missing.
  • Release packaging: benchmark-results.tar.gz created and attached to GitHub release; manifest and README are produced during packaging.
  • Artifact retention: 30 days on workflow artifacts.

Release metadata (from commits)

  • Commits included: 3
    • feat(ci): add GitHub Pages deployment to benchmark workflow; add documentation for Pages (f2a1baa)
    • chore(release): bump package version to 1.0.5 (b33146d)
    • 1.0.5-dev.0 (development tag commit) (53f33b8)
  • Contributor(s): Tim O'Brien

Final notes and recommendations

  • No code-level breaking changes detected; this release is safe for users relying on benchmark scripts. The main impact is the CI/infra behavior and the new public site.
  • Confirm Pages enabling and organization-level policies for Actions permissions before rolling this out in a managed environment.
  • Monitor the first few runs for: (1) artifact upload/download correctness, (2) content published to Pages being the intended report instead of fallback, and (3) Actions permission errors (if any).

Changelog (commit excerpts)

  • feat(ci): add GitHub Pages deployment to benchmark workflow; add documentation for Pages — added pages/id-token permissions and deploy-to-pages job; added CHANGES_MADE.md, DEPLOYMENT_SUMMARY.md, GITHUB_PAGES_SETUP.md, QUICK_START.md, docs/README.md, DEPLOYMENT_DIAGRAM.txt
  • chore(release): bump package version to 1.0.5 — finalize release and remove -dev pre-release suffix in package.json

(End of release notes.)

Assets 2
Loading