Skip to content

v2.0.md

Latest commit

 

History

History
76 lines (59 loc) · 4.98 KB

v2.0.md

File metadata and controls

76 lines (59 loc) · 4.98 KB

Release notes: Documentation set v2.0

This release covers changes from v1 to v2 of the GitHub Issues API documentation set (portfolio repo).

Version anchors (commit-grounded)

  • v1 baseline (GitHub repo docs-only): 4de1450 on 2026-02-01
    docs: add evidence-backed guides (quickstart, pagination, troubleshooting)
  • v2 release: 3c054e2 on 2026-02-02
    docs: publish Guides HTML and fix related links
  • Follow-up (discoverability): ab5bcca on 2026-02-02
    docs: link from README/spec

Summary

v2 publishes the task-based Guides as a static HTML site under GitHub Pages alongside the Redoc reference docs. It also fixes “Related links” so they resolve to canonical GitHub URLs (instead of behaving like local file links when clicked from generated HTML), and makes the Guides rebuild process consistent via scripts/build-guides.mjs.

Highlights

  • Guides HTML ships with Pages (docs/guides/index.html + per-guide HTML pages + shared styling/navigation).
  • Related links are web-safe (canonical GitHub URLs in guide content).
  • Reference docs can hand off to tasks via README and OpenAPI externalDocs pointing to the Guides index.

What changed (v1 → v2)

v1: Evidence-backed guide set added (4de1450)

  • Added a /guides documentation set to complement the OpenAPI reference docs.
  • Includes Quickstart, Pagination & Filtering behaviors, Errors & Troubleshooting, and a Support Checklist.
  • Guides are aligned to observed API behavior and validated against evidence artifacts and the test suite.
  • Designed for skimmability and real-world use (task-based steps, common failure modes, reproducible troubleshooting).

v2: Guides published as HTML + links fixed (3c054e2)

  • Added a generated Guides site under docs/guides/ with shared styling and navigation.
  • Normalized “Related links” in guide markdown to point to canonical GitHub URLs.
  • Generates a static Guides site in docs/guides/ with shared styling and navigation.
  • Includes/updates scripts/build-guides.mjs so Guides can be rebuilt consistently.
  • Keeps Pages output in /docs so the reference docs and guides ship together.

Follow-up: README/spec link wiring (ab5bcca)

  • Updated repo README with the live Guides URL plus source Markdown links.
  • Fixed OpenAPI externalDocs to point to the Guides index and kept official docs referenced in info.description.

Breaking changes (docs contract, not GitHub’s API)

These are “breaking” only for the documentation set’s published behavior.

1) Guides are now HTML-first for public sharing

Change: The recommended share link is the Guides HTML index and per-guide .html pages on GitHub Pages.
Who is affected: Anyone sharing guides/*.md as the “live docs” experience.
Action: Update shared links to the HTML pages. Keep Markdown links for repo browsing only.
Verify: Open the Guides index on Pages and confirm each guide opens.

2) “Related links” must be canonical GitHub URLs

Change: Relative links like glossary.md can resolve incorrectly when content is rendered into standalone HTML.
Action: Use canonical GitHub URLs (tree/blob) in “Related links”.
Verify: Click every “Related links” item from a guide HTML page and confirm it opens on GitHub.

3) Generated HTML is output, not editable source

Change: docs/guides/*.html is generated output.
Action: Edit guides/*.md, run the build script, then commit regenerated HTML.
Verify: Make a small Markdown edit, rebuild, and confirm HTML updates.

Deprecations

  • Deprecated (v2.0): Local/relative file links in “Related links” intended for the published site.
  • Removal target (v2.1): Remove any remaining relative “Related links” and standardize on canonical GitHub URLs everywhere.
  • Replacement: Canonical GitHub URLs + Pages .html links.

Compatibility table

Scenario v1 behavior v2 behavior Impact Action
Reader using GitHub Pages Guides not available as a site Guides HTML site exists under /guides/ Medium Share Guides index URL
Reader clicking “Related links” from HTML May resolve to local/relative paths Opens canonical GitHub URLs Low None
Maintainer updating guides No consistent rebuild expectation Rebuild via script + commit output Medium Run node scripts/build-guides.mjs

Known issues / watch-outs

  • Path assumptions: If you ever move the Guides output folder, confirm every nav link still resolves relative to /guides/ (for example, links to index.html and the per-guide .html pages).
  • Mixed link sharing: GitHub-rendered Markdown (guides/*.md) is fine for repo browsing, but the best “docs site” experience is the Pages HTML (/guides/*.html). Mixing them in the same “start here” path can confuse readers.
  • Avoid committing dependencies: If node_modules/ ever shows up in a docs commit, treat it as accidental. Prefer committing source + built output, not dependencies.