microsoft / microsoft/typespec
Post 1.0 versioning
- 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
Assessment
This issue has not been assessed yet.