Skip to content

Latest commit

 

History

History
83 lines (62 loc) · 3.3 KB

README.rst

File metadata and controls

83 lines (62 loc) · 3.3 KB
Raw

Simple Versioning

Introduction

Many projects have problem with version numbering scheme, what can be easily seen in open source projects - each of them have a different one. One great approach to make one consistent scheme is SemVer. What you can see here is another approach, a bit different, but mostly inspired by mentioned SemVer.

Definitions

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.

  • Chunks - parts of version number (without suffix) separated by dot. In version 1.2.0.453-chuck-testa chunks are 1, 2, 0 and 453.
  • Series - releases corelated by first non-zero chunk in version number (releases with versions 0.1, 0.1.1, 1, 1.2, 1.3-dev are all released under series 1)
  • Unstable version - release where version number points to revision, which work is found to be unstable, or its interfaces (like api) may change in the future. Unstable release is release that must not be used in production environments and its interfaces must not be a base to build other components.
  • Stable version - release where version number points to revision, which work is found to be stable (and preferably tested). If it is another stable version from given series it must keep backward compatibility with previous stable version(s) from given series.
  • Development version - release where version number points to revision, which was developed after releasing first stable version, and has additional features or fixes, but is not yet fully tested or stable or is released for review. It must keep backward compatibility with series under which it was released, but may contain bugs or even, not intended, backward compatibility breaks. Development release is release that must not be used in production envrionments and its interfaces must not be a base to build other components.

Simple Versioning Specification

  • Every version number must take form of ^(0\.)?[1-9][0-9]*(\.[0-9]+)*(-[a-zA-Z][a-zA-Z-_0-9]*)?$. (What gives you proper version numbers like 0.1, 2.0, 3, 3.1, 2.0.1-dev and wrong like 0.0.1, 2.0alpha or 2.0.0RC1, 2.1-2)
  • Every unstable version must have number that starts with 0.X where X is number of series, under which later stable versions will be released.
  • Each chunk of version number must be considered as integer and must increase numerically (with exception for alphanumerical suffix, which, obviously, can't). For example: 1.9 -> 1.10 -> 1.11.

Examples

This simple scheme may be at first difficult to understand, how to use it in practice and solve many versioning problems, therefore please check cookbook to grasp more info about it.

Feedback

If you want to leave some feedback, please open an issue on GitHub

License

No license - no problem.

Thanks

To all my friends, which drank with me hectolitres of beer while discussing about different version number schemes - thanks :).