sentenz / convention

General articles, conventions, and guides.
https://sentenz.github.io/convention/
Apache License 2.0
4 stars 2 forks source link

Create an article about `Versioning` #277

Open sentenz opened 1 year ago

sentenz commented 1 year ago

Versioning

Versioning in software development refers to the practice of assigning unique identifiers or labels to different releases of a software product. This makes it possible to track and distinguish between different iterations, ensuring that changes are managed systematically over time.

Version control systems facilitate collaborative development by recording and managing changes to source code. Branches, tags or commit hashes are used to locate specific versions within the development history. This systematic approach to versioning helps developers maintain code integrity, track progress, and facilitate seamless collaboration across teams.

1. Category

1.1. Semantic Versioning (SemVer)

Semantic Versioning (SemVer) is a versioning convention designed for software libraries and applications to communicate the nature of changes in a standardized way. SemVer follows a three-part version number format MAJOR.MINOR.PATCH.

SemVer enables developers and users to quickly understand the nature and impact of changes by examining version numbers. It promotes a clear and predictable approach to versioning, facilitating dependency management, and ensuring compatibility across different software components.

  1. Conventions and Standards

    • MAJOR

      Increments the MAJOR version in case of incompatible API changes.

      Example: 1.0.02.0.0

    • MINOR

      Increments the MINOR version when adding backwards compatible functionality.

      Example: 1.0.01.1.0

    • PATCH

      Increments the PATCH version in the case of backwards compatible bug fixes.

      Example: 1.0.01.0.1

    • Pre-release

      A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version.

      Examples: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.

    • Build metadata

      Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence.

      Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

  2. Tools and Frameworks

    • semantic-release

      semantic-release automates the package release workflow, including determining the next version number, generating the release notes, and publishing the package. A utility for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.

    • commit-and-tag-version

      commit-and-tag-version automates the versioning and CHANGELOG generation process. A utility for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.

    • release-please

      release-please automates CHANGELOG generation, the creation of GitHub releases, and version tag. A utility for versioning using SemVer and CHANGELOG generation powered by Conventional Commits.

1.2. Calendar Versioning (CalVer)

Calendar Versioning (CalVer) is a versioning scheme that uses dates as the basis for version numbers, providing a more human-readable and chronological representation of software releases. CalVer uses the composed version identifiers in the date format YYYY.MM.DD.MICRO versioning scheme.

CalVer is popular in projects where a straightforward, easily understandable versioning system is beneficial. It aligns well with development practices that emphasize frequent and incremental releases, providing transparency about the software's evolution over time.

NOTE The components allow for flexibility in choosing the level of granularity for versioning, depending on the project's needs. Combine these components to form version numbers based on the desired level of detail and chronological representation. For example, a version could be represented as YYYY.MM, YY.0M, YY.0M.MICRO, or YY.WW.

  1. Conventions and Standards

    • YYYY

      Full year.

      Example: 2006, 2016, 2106

    • YY

      Short year.

      Example: 6, 16, 106

    • 0Y

      Short year with a zero-padded.

      Example: 06, 16, 106

    • MM

      Month of the year.

      Example:1, 2, 11, 12

    • 0M

      Month of the year with a zero-padded.

      Example: 01, 02, 11, 12

    • WW

      Week of the year.

      Example: 1, 2, 33, 52

    • 0W

      Week of the year with a zero-padded.

      Example: 01, 02, 33, 52

    • DD

      Day of the month.

      Example: 1, 2, 30, 31

    • 0D

      Day of the month with a zero-padded.

      Example: 01, 02, 30, 31

    • MICRO

      A counter for releases on the same day. Numerical value indicating a micro version or build identifier. Optionally add a modifier to the version, such as dev, alpha, beta, or rc1.

      Example: 1, 8, 21, 103, 21-aloha, 103-rc1

  2. Tools and Frameworks

    • release-calver

      release-calver automates the versioning and CHANGELOG generation process.

2. References