Skip to content

Instantly share code, notes, and snippets.

@conartist6

conartist6/index.md

Last active September 7, 2024 20:19
Show Gist options
  • Save conartist6/37be2e179d286fe7be276e5abe32ff57 to your computer and use it in GitHub Desktop.
Save conartist6/37be2e179d286fe7be276e5abe32ff57 to your computer and use it in GitHub Desktop.
Download ZIP
Semver-0 proposal
Raw
index.md

0-based Semantic Versioning 0.0.0

Summary

0-based semver is a valid subset of Semver 2.0.0 where version numbers look like (for example) 0.24.1. 0-based semver also uses this specification to govern its own versions.

Given a triplet version number in the format X.Y.Z:

  1. X must always be 0
  2. The first initial development version of a package should be 0.0.1
  3. The first version of a package with a stable public API should be 0.1.0
  4. The package author must bump Y when the public API changes
  5. The package author should bump Z when fixing bugs or improving security
  6. Z should start over at 0 for any release which bumps Y

Note that it is acceptable for two versions to be the same. Version 0.0.1 may be "promoted" to 0.1.0 for example if the first published version of the package proves stable enough for production use.

Additional labels for pre-release and build metadata are available using the same mechanism as semver.

Introduction

This specification is meant to formalize a versioning scheme long supported by npm and used most frequently by packages which are undergoing initial development or which expect to have ongoing releases containing breaking changes.

The specification should accomplish this by setting clear expectations for both producers and consumers of package code: a social contract which if followed by both parties will act as an effective shield against certain kinds of breakages and vulnerabilities. The specification can accomplish this only to the extent that some trust exists between the publisher and the consumer. This can be either institutional trust, or trust-but-verify trust.

It is the responsibility of the package consumer:

  • To consider the operational risks of trusting any third parties to alter code that runs in your environment.
  • To use the package in accordance with its public APIs. If a package's behavior is known to deviate from its documented public API, the consumer must report the bug and must not rely on the non-spec behavior.

It is the responsibility of the package author:

  • To review bug reports and provide at the most basic level feedback as to whether given behavior is a bug (subject to change in any release) or a feature (guaranteed not to change except in major releases).
  • To make a best effort not to cause real breakages for consumers, including by deprecating releases which have accidentally broken the guarantees of semver.

Specification

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119.

  1. Software using 0-based Semantic Versioning MUST also be compatible with Semantic Versioning 2.0.0. Where the specifications disagree, this specification's language shall be considered normative

  2. For this specification to apply, it MUST be intentionally caused to be presented to the consumer of the package by its author. This action represents the offer of a friendly agreement which SHALL NOT have force as a legal contract nor penalty for any damage caused. The specification may be provided to the consumer by publishing a text document, a link to a web page containing this text, or formalized metadata which commonly causes an appropriate link to be displayed.

  3. A normal version number MUST take the form 0.Y.Z where Y and Z are non-negative integers, and MUST NOT contain leading zeroes. Y is the major version, and Z is the patch version. Each element MUST increase numerically. For instance: 0.1.9 -> 0.1.10 -> 0.2.0.

  4. Version 0.0.0 SHOULD be used to denote code which is not published, and is therefore not necessarily compliant with any published version's contract. When source code can be consumed as if it were a published package, its version SHOULD be 0.0.0.

  5. Once a versioned package has been released, the contents of that version MUST NOT be modified. Any modifications MUST be released as a new version. This guarantee does not apply to version 0.0.0

  6. Version 0.1.0 defines the public API. Before a public API has been released, a package MUST be considered by the consumer to have breaking changes in every version. Once the package is > 0.1.0 breaking changes MUST NOT be released except in a new major version.

  7. Major version Y (0.Y.z | Y > 0) MUST be incremented when a new version of a public API is released. A major version of 0 indicates that no public API has yet been released. Major versions MAY also include minor and patch level changes. Patch version MUST be reset to 0 when major version is incremented.

  8. Patch version Z (0.y.Z | y > 0) MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change or one that fixes external behavior which is incompatble with the stated public API.

  9. Precedence between versions MUST be interpreted in accordance with Semantic Versioning 2.0.0.

  10. All versions which are valid in Semantic Versioning 2.0.0 and for which the first digit is 0 MUST be valid 0-based Semver versions. This includes, at a minimum, prereleases like 0.1.0-alpha.1

License

Public Domain - CC0

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment