Skip to content

Add "Multiple API Versions" pattern and restructure patterns index#1962

Open
Copilot wants to merge 3 commits intomainfrom
copilot/create-pattern-for-multiple-versions
Open

Add "Multiple API Versions" pattern and restructure patterns index#1962
Copilot wants to merge 3 commits intomainfrom
copilot/create-pattern-for-multiple-versions

Conversation

Copy link
Copy Markdown
Contributor

Copilot AI commented Apr 26, 2026

Summary

Adds a new $.minVersion() pattern page and rewrites the patterns index introduction, which had grown into a single unwieldy run-on paragraph.

docs/patterns/multiple-versions.md (new)

  • Problem/Solution/Example/Consequences/Related Patterns structure matching existing pattern pages
  • Shows how to configure multiple versioned specs under one group using counterfact.yaml
  • Demonstrates layered $.minVersion() branching in a single shared handler across v1/v2/v3
  • Covers TypeScript type-narrowing after a minVersion check

docs/patterns/index.md

  • Replaces the single 300-word paragraph with six labelled sections: Getting started, Organizing state, Runtime control, Versioned and multi-spec APIs, Long-term reliability, Integration strategies
  • Adds Multiple API Versions row to the All patterns table
Original Prompt

Create a pattern that describes working with multiple versions of an API and using $.minVersion().

Also rewrite the patterns index introduction. It's gotten very long. It should be broken up into multiple paragraphs, and possible even have section headers.

Manual acceptance tests

  • docs/patterns/multiple-versions.md renders correctly and all Related Patterns links resolve to existing files
  • docs/patterns/index.md introduction displays as distinct labelled sections rather than one long paragraph
  • "Multiple API Versions" row appears in the All patterns table and its link navigates to the new page
  • All pre-existing pattern links in index.md still resolve correctly
  • The $.minVersion() example in the new pattern matches the runtime semantics: true when current version ≥ min in declaration order, absent on unversioned runners
  • The counterfact.yaml configuration example in multiple-versions.md uses the correct YAML spec array format with source, group, and version keys

Tasks

  • Created docs/patterns/multiple-versions.md with full pattern structure covering configuration (via counterfact.yaml), runtime helpers, TypeScript narrowing, and consequences
  • Rewrote docs/patterns/index.md introduction into six sectioned paragraphs; added new pattern to All patterns table
  • Added .changeset/multiple-versions-pattern.md (patch bump)
  • Updated configuration example in multiple-versions.md to use counterfact.yaml YAML format instead of the programmatic counterfact() API

Copilot AI changed the title [WIP] Create a pattern for working with multiple versions of API Add "Multiple API Versions" pattern and restructure patterns index Apr 26, 2026
Copilot AI requested a review from pmcelhaney April 26, 2026 01:59
@pmcelhaney pmcelhaney marked this pull request as ready for review April 26, 2026 02:56
Comment thread docs/patterns/multiple-versions.md Outdated

## Solution

Configure each versioned spec as a separate entry in the `specs` array passed to `counterfact()`. Give them the same `group` and different `version` labels. Counterfact generates a shared route file per path and injects two helpers into the handler's `$` argument at runtime:
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Explain in terms of the config file, not the API.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in 4e3d1d2. The Solution section now says to list specs under the spec key in counterfact.yaml, and the Configuration example is a YAML block instead of a TypeScript counterfact() call.

Copilot AI requested a review from pmcelhaney April 26, 2026 05:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Create a pattern for working with multiple versions

2 participants