xamarin-macios/dotnet/VERSIONS.md

Versioning

Scheme

Our NuGet packages are versioned using Semver 2.0.0.

This is the scheme: OsMajor.OsMinor.InternalRelease[-prereleaseX]+sha.1b2c3d4.

• Major: The major OS version.
• Minor: The minor OS version.
• Patch: Our internal release version based on 100 as a starting point.
  • Service releases will bump the last two digits of the patch version
  • Feature releases will round the patch version up to the nearest 100 (this is the same as bumping the first digit of the patch version, and resetting the last two digits to 0).
  • This follows how the dotnet SDK does it.
• Pre-release: Optional (e.g.: Xcode previews, CI, etc.)
  • For CI we use a ci prefix + the branch name (cleaned up to only be alphanumeric) + the commit distance (number of commits since any of the major.minor.patch versions changed).
    • Example: iOS 15.0.100-ci.main.1234
    • Alphanumeric means a-zA-Z0-9-: any character not in this range will be replaced with a -.
  • Pull requests have pr prefix, followed by gh+ PR number + commit distance.
    • Example: tvOS 15.1.200-ci.pr.gh3333.1234
  • If we have a particular feature we want people to subscribe to (such as an Xcode release), we publish previews with a custom pre-release identifier:
    • Example: iOS 15.1.100-xcode13-1.beta.1
    • This way people can sign up for only official previews, by referencing iOS *-xcode13-1.beta.*
    • It's still possible to sign up for all xcode13-1 builds, by referencing iOS *-ci.xcode11-3.*
• Build metadata: Required Hash
  • This is sha. + the short commit hash.
    • Use the short hash because the long hash is quite long and cumbersome. This leaves the complete version open for duplication, but this is extremely unlikely.
  • Example: iOS 14.0.100+sha.1a2b3c
  • Example (CI build): iOS 15.0.100-ci.main.1234+sha.1a2b3c
  • Since the build metadata is required for all builds, we're able to recognize incomplete version numbers and determine if a particular version string refers to a stable version or not.
    • Example: iOS 15.0.100: incomplete version
    • Example: iOS 15.0.100+sha.1a2b3c: stable
    • Example: iOS 15.0.100-ci.d17-0.1234+sha.1a2b3c: CI build
    • Example: iOS 15.0.100-xcode13-1.beta.1+sha.1a2b3c: official preview
      • Technically it's possible to remove the prerelease part, but we’d still be able to figure out it’s not a stable version by using the commit hash.