microsoft / microsoft/typespec

Post 1.0 versioning

Open
#6,751 6 comments 0 reactions 1 assignee Claimed by @timotheeguerin View on GitHub
design:proposed eng triaged:core
Dominant language
Java
Stars
5.9k
Forks
394
Avg merge
1d 23h
Merged PRs (30d)
104

Description

# Post 1.0 versioning

Current problem we'll have 3 different versions in our libraries:

For context in the following examples `n` and `m` refer to numbers shared across packages. `x` refer to an number that each package can have independently.

- `1.n.x`: For all stable packages(compiler, http, openapi3, etc.)
- `0.m.x`: For all preview packages(xml, protobuf, etc.)
- `0.1.0-alpha.x`: For all alpha packages(js and csharp emitters)
- Other separate packages that are not libraries, we'll ignore those as they can release on their own versioning (e.g. Playground, bundler, etc.)

## Current Terminology

Right now we have the following terminology:

- **Stable**: `1.n.x` packages
- **Preview**: `0.m.x` packages
- **Alpha**: `0.1.0-alpha.x` packages

Nothing against changing this to something else like `preview` is now `beta`

## Options

### Option 1: Only use `1.n.x` and `0.m.x` versions

This would reduce the number to manage to 2 but we'd loose the ability to differentiate alpha from preview packages.

### Option 2: All packages use `1.n.x[-status]`

- **Stable**: `1.n.x`
- **Preview**: `1.n.0-preview.x`
- **Alpha**: `1.n.0-alpha.x`

This would result in for example

| Example | `@typespec/compiler` | `@typespec/http` | `@typespec/xml` | `@typespec/http-server-js` |
| --------------------------------- | -------------------- | ---------------- | ----------------- | -------------------------- |
| Release of 1.1 | `1.1.0` | `1.1.0` | `1.1.0-preview.0` | `1.1.0-alpha.0` |
| Http and http-server-js bug fixes | `1.1.0` | `1.1.1` | `1.1.0-preview.0` | `1.1.0-alpha.1` |
| Release of 1.2 | `1.2.0` | `1.2.0` | `1.2.0-preview.0` | `1.2.0-alpha.0` |

Advantages of this approach is all our libraries would share the same `1.n` version which would make it easy to get the compatible versions.

Disadvantages is that npm semver doesn't count `^1.1.0-preview.0` as a compatible version with `1.1.1-preview` so we have to use the prerelease version for patch release. The patch number will always be 0 in those cases

## Versioning terminology

| Descriptive | Current terminology | Option 1 | Option 2 |
| ------------------------------------------------------------------------------------------- | ------------------- | -------- | -------- |
| Stable | Stable | Stable | Stable |
| The library is about to be released, only bug fixes | RC | RC | RC |
| The library might still see some breaking change as we get feedback but they should be rare | Preview | Beta | Preview |
| The library is now mature enough but breaking change as still likely | | | Beta |
| The library is in early development and will see significant changes | Alpha | Alpha | Alpha |

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.