update readme with versioning scheme

oxidecomputer · May 6, 2024 · dfdbe2c · dfdbe2c
1 parent 91bbb7e
commit dfdbe2c
Show file tree

Hide file tree

Showing 4 changed files with 44 additions and 15 deletions.
diff --git 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 <schema url or file> <output dir>
+```
+
+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
@@ -0,0 +1,18 @@
+# Releasing this library
+
+This is a spot for documentation not useful to the end user.
+
+## Publishing to npm
+
+```
+npm version <bump-type>
+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
diff --git 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",