[Issue #370] Generate json schemas per version

[widal001]

Summary

Auto-generates JSON schemas for each version of a model, field, enum etc.

• Fixes [JSON schema versioning] Emit versioned schemas #370
• Time to review: [xx] minutes

Changes proposed

What was added, updated, or removed in this PR.

• Changelog emitter: Updates the changelog output to be more structured, so it could be used to generate different versions of each JSON schema
• Website
  • Updates SchemaChangelog to work with new changelog output
  • Adds script to generate JSON schemas for each version of a given model

Context for reviewers

Testing instructions, background context, more in-depth details of the implementation, and anything else you'd like to call out or ask reviewers. Explain how the changes were verified.

This PR doesn't yet publish all of JSON schema versions on the website. I had a few questions about where/how we wanted to do this:

• Right now we have the latest version of each schema available at /schemas/yaml/ we could:
  • Preserve /schemas/yaml/ for the latest version but then expose all versions in /schemas/yaml/versions/[v1 | v2 | v3]/
  • Make the latest available at /schemas/yaml/latest/ and then do /schemas/yaml/v2/ etc. for earlier versions
  • Treat the latest version the same as others and expose them all at /schemas/yaml/v3/ etc.
• In terms of how we want to link to these published versions, do we want to:
  • Link to them under the "JSON schema" tag in the formats section
  • Add a link to each version in the changelog table?

Additional information

Screenshots, GIF demos, code examples or output to help show the changes working as expected.

Schema versions

1. Checkout the PR
2. Run pnpm --filter typespec-versioning-changelog test:coverage to build the updated changelog emitter
3. Run npm run typespec && npm run generate:versioned-schemas from within the website/ directory
4. Go to tsp-output/schemas/ to view the auto-generated schemas

5. View the auto-generated schemas for v0.2.0/Form.yml and v0.3.0/FormBase.yml

Changelog outputs

Old output

{
  "FormBase": [
    {
      "version": "0.2.0",
      "changes": [
        "Added `Form` model"
      ]
    },
    {
      "version": "0.3.0",
      "changes": [
        "Renamed model from `Form` to `FormBase`",
        "Added `version` field"
      ]
    }
  ]
}

New output

{
  "versions": ["0.1.0", "0.2.0", "0.3.0"],
  "logs": {
    "FormBase": {
      "0.2.0": [
        {
          "message": "Added `Form` model",
          "action": "added",
          "targetKind": "model",
          "currTargetName": "Form"
        }
      ],
      "0.3.0": [
        {
          "message": "Renamed model from `Form` to `FormBase`",
          "action": "renamed",
          "targetKind": "model",
          "prevTargetName": "Form",
          "currTargetName": "FormBase"
        },
        {
          "message": "Added `version` field",
          "action": "added",
          "targetKind": "field",
          "currTargetName": "version"
        }
      ]
    }
  }
}

[github-actions]

🚀 Website Preview Deployed!

Preview your changes at: https://cg-pr-426.billy-daly.workers.dev

This preview will be automatically deleted when the PR is closed.

[DavidDudas-Intuitial]

I added one non-blocking comment.

In response the questions posed in the Summary:

• re: the latest version of each schema available at /schemas/yaml/
  I am in favor of preserving /schemas/yaml/ for the latest version and also exposing all versions in /schemas/yaml/versions[v0.1 | v0.2 | etc].

• re: how we want to link to these published versions
  IMO the Changelog table is the perfectly contextual place to link to the versioned schemas. Changes and versions go hand in hand, whereas the Formats section is more about examples of the latest version in different languages.

[github-actions]

🗑️ Preview Cleaned Up

The preview for this PR has been automatically deleted.