From 60760981e30b36a9c7948f3b6c5137a350e01258 Mon Sep 17 00:00:00 2001 From: David Crespo Date: Mon, 6 May 2024 09:46:37 -0500 Subject: [PATCH] update readme with versioning scheme --- oxide-openapi-gen-ts/README.md | 34 +++++++++++++++++--------- oxide-openapi-gen-ts/docs/releases.md | 25 +++++++++++++++++++ oxide-openapi-gen-ts/package-lock.json | 4 +-- oxide-openapi-gen-ts/package.json | 3 ++- 4 files changed, 51 insertions(+), 15 deletions(-) create mode 100644 oxide-openapi-gen-ts/docs/releases.md diff --git a/oxide-openapi-gen-ts/README.md b/oxide-openapi-gen-ts/README.md index 3684e99..079f703 100644 --- a/oxide-openapi-gen-ts/README.md +++ b/oxide-openapi-gen-ts/README.md @@ -4,6 +4,16 @@ This is a TypeScript OpenAPI client generator built for use with schemas generated by [Dropshot](https://github.com/oxidecomputer/dropshot). It has not been tested on any other specs and is unlikely to handle them well. +## Usage + +```sh +npx @oxide/openapi-gen-ts@version +``` + +Note that fixing a version with `@0.1.0` is important because you don't want +your generated output to between runs. See the Versioning section below for +details. + ## Interesting files The core logic for looping over the spec and creating the methods is in @@ -14,13 +24,12 @@ OpenAPI schemas to TS types is in [`src/schema/types.ts`](./src/schema/types.ts) The files in [`src/client/static/`](./src/client/static/) are copied over to the client as-is during generation. We generate several distinct pieces: -| File | Description | -| ------------------------------------------- | ------------------------------------------------------------------------------------------------------ | +| File | Description | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | [`Api.ts`](../api/src/Api.ts) | A [Fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)-based TS client to the Oxide API | | [`validate.ts`](../api/src/validate.ts) | [Zod](https://github.com/colinhacks/zod) validators for API request and response types | | [`msw-handlers.ts`](../api/src/msw-handlers.ts) | Helpers used to build a mock API with [Mock Service Worker](https://mswjs.io/) in the console repo | - ## Why a custom generator? We tried many existing generators, and while most worked in a basic sense, we @@ -33,16 +42,17 @@ same for Rust ([progenitor](https://github.com/oxidecomputer/progenitor) and that a special-purpose generator could be dramatically simpler than a general one, so writing one was easier than existing generators made it look. -## Generating the client - -```bash -# optional: update omicron sha in OMICRON_VERSION -./tools/gen.sh -``` - The TypeScript client code will be written to `oxide-api/src`. -## Publishing to npm +## Versioning scheme -TBD +Generator versions on npm are semver-ish. Breaking changes to the generator's +own API (not the generated output) should be major releases. Currently, the +generator has no programmatic API and can only be used as a CLI app (e.g., +through `npx`), so we will consider the CLI to be the external API. +| Version bump | Example changes | +| ------------ | -------------------------------------------------------------- | +| Major | Breaking changes to CLI args or flags | +| Minor | Semantic changes (i.e., modulo formatting) to generated output | +| Patch | Internal changes or non-meaningful changes to generated output | diff --git a/oxide-openapi-gen-ts/docs/releases.md b/oxide-openapi-gen-ts/docs/releases.md new file mode 100644 index 0000000..9eaa3ba --- /dev/null +++ b/oxide-openapi-gen-ts/docs/releases.md @@ -0,0 +1,25 @@ +# Releasing this library + +This is a spot for documentation not useful to the end user. + +## Publishing to npm + +This will change when we figure out automatic publishing from GH actions. + +``` +npm version + +# now commit and push that because we don't want to publish things that aren't +# on github + +# now build and publish +npm run build # runs tsup and outputs in dist +npm publish +``` + +## Generating the client in this repo + +```bash +# optional: update omicron sha in OMICRON_VERSION +./tools/gen.sh +``` diff --git a/oxide-openapi-gen-ts/package-lock.json b/oxide-openapi-gen-ts/package-lock.json index 0c04a10..128a174 100644 --- a/oxide-openapi-gen-ts/package-lock.json +++ b/oxide-openapi-gen-ts/package-lock.json @@ -1,12 +1,12 @@ { "name": "@oxide/openapi-gen-ts", - "version": "0.1.10", + "version": "0.1.11", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@oxide/openapi-gen-ts", - "version": "0.1.10", + "version": "0.1.11", "license": "MPL-2.0", "dependencies": { "prettier": "2.7.1", diff --git a/oxide-openapi-gen-ts/package.json b/oxide-openapi-gen-ts/package.json index 7ea1933..789ccf9 100644 --- a/oxide-openapi-gen-ts/package.json +++ b/oxide-openapi-gen-ts/package.json @@ -1,6 +1,6 @@ { "name": "@oxide/openapi-gen-ts", - "version": "0.1.10", + "version": "0.1.11", "description": "OpenAPI client generator used to generate Oxide TypeScript SDK", "keywords": [ "oxide", @@ -33,6 +33,7 @@ }, "scripts": { "build": "tsup-node && mkdir -p dist/static/ && cp src/client/static/util.ts dist/static/ && cp src/client/static/http-client.ts dist/static/", + "fmt": "prettier --write .", "lint": "eslint .", "pretest": "../tools/gen.sh", "test": "vitest",