Explicitly Use Semantic Versioning

[isosphere]

https://github.com/hometown-fork/hometown is a fork of mastodon that stays updated with upstream changes. Our needs for versioning are similar. Here's the section of the hometown readme regarding versioning:

Hometown uses semantic versioning and follows a versioning convention like v1.0.0+2.9.3. The 1.0.0 part is the actual Hometown version number, and then the 2.9.3 after the + sign is what's known in semantic versioning as "build metadata". It just means that a particular release is synchronized with Mastodon version 2.9.3, so for example an upgrade from v1.0.0+2.9.2 to v1.0.0+2.9.3 would upgrade Mastodon but not provide any new Hometown features or fixes.

I like that approach more than ours:

0.x.y Versions that have the same x value target the same version of Yew.

There is currently no indication of which version of Bootstrap is targeted, however, we’ll try to target the previous release pipeline. For example as of this writing the latest boostrap is 5.2.x, so we’ll try to target the latest 5.1.x version.

We might need to include two separate kinds of build metadata: one for bootstrap, and another for yew.

I'm not sure how well this will play with cargo, though.

[isosphere]

Cargo explicitly references https://semver.org/ - build metadata should be legal.

Here's an issue someone had with this in 2016: https://github.com/rust-lang/cargo/issues/2939. All related issues seem to be closed, I think it was an issue, but it's resolved. the semver crate is responsible for processing this.

Something to consider:

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, 1.0.0+21AF26D3----117B344092BD.

Hrm. Looks like the standard doesn't want us to rely so much on build metadata.

If we change Yew versions, that's probably going to be a major change for us each time - I don't think our users can mix and match Yew dependencies safely like that - it'll be incompatible without the change, i.e.: breaking change.

Therefore, each Yew change must increment our "MAJOR" version.

Bootstrap may or may not be a major change. That project is old and stable, and has lots of patch releases. Most changes will not be noticed by our end users - especially given that we are saving them from interacting with the underlying bootstrap objects and instead using our Rust abstractions.

[isosphere]

I have studied the semantic versioning document; as a result I don't think we need to specify any build metadata. We just have to be mindful about our public API and when we break it. We're still earlier than 1.0.0 at the moment, so breaking changes should be expected.

I reaffirm my above statement that a Yew version change, as of this writing, will necessarily be a major release for us. This will change when Yew reaches 1.0.0; at that point we'll have to make a judgment call for each update.

I have updated our README.md files to indicate that we will conform to semantic versioning.

I present here my notes on semantic versioning:

• Semantic Versioning 2.0.0 Semantic Versioning.pdf
  • MAJOR.MINOR.PATCH; increment:
    • MAJOR version when you make incompatible API changes
      • Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.
      • Version 1.0.0 defines the public API.
      • MUST be incremented if any backward incompatible changes are introduced to the public API.
      • It MAY also include minor and patch level changes.
      • Patch and minor versions MUST be reset to 0 when major version is incremented.
    • MINOR version when you add functionality in a backward compatible manner
      • It MUST be incremented if any public API functionality is marked as deprecated.
      • It MAY be incremented if substantial new functionality or improvements are introduced within the private code
      • It MAY include patch level changes.
      • Patch version MUST be reset to 0 when minor version is incremented.
      • Patch and minor versions MUST be reset to 0 when major version is incremented.
    • PATCH version when you make backward compatible bug fixes
      • A bug fix is defined as an internal change that fixes incorrect behavior.
      • Patch version MUST be reset to 0 when minor version is incremented.
      • Patch and minor versions MUST be reset to 0 when major version is incremented.
  • Precedence refers to how versions are compared to each other when ordered.
    • Precedence MUST be calculated by separating the version into major, minor, patch and pre-release identifiers in that order
    • Build metadata does not figure into precedence
    • Precedence is determined by the first difference when comparing each of these identifiers from left to right as follows: Major, minor, and patch versions are always compared numerically
    • When major, minor, and patch are equal, a pre-release version has lower precedence than a normal version
    • Precedence for two pre-release versions with the same major, minor, and patch version MUST be determined by comparing each dot separated identifier from left to right until a difference is found
      • Identifiers consisting of only digits are compared numerically.
      • Identifiers with letters or hyphens are compared lexically in ASCII sort order
      • Numeric identifiers always have lower precedence than non-numeric identifiers.
      • A larger set of pre-release fields has a higher precedence than a smaller set, if all of the preceding identifiers are equal
        • 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 <1.0.0-rc.1 < 1.0.0
  • pre-release and metadata
    • A pre-release version MAY be denoted by appending a hyphen and a series of dot separated identifiers immediately following the patch version.
      • Identifiers MUST comprise only ASCII alphanumerics and hyphens[0-9A-Za-z-]
      • Identifiers MUST NOT be empty.
      • Numeric identifiers MUST NOT include leading zeroes.
      • Prerelease versions have a lower precedence than the associated normal version
        • 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
    • 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 hyphens [0-9A-Za-z-]
      • Identifiers MUST NOT be empty.
      • Build metadata MUST be ignored when determining version precedence.
      • Thus two versions that differ only in the build metadata, have the same precedence.
  • If the dependency specifications are too tight, you are in danger of version lock
  • If dependencies are specified too loosely, you will inevitably be bitten by version promiscuity (assuming compatibility with more future versions than is reasonable)
  • For this system to work, you first need to declare a public API. This may consist of documentation or be enforced by the code itself.
    • For a project, that's the crate documentation
      • keep things private unless you're sure you want to commit to maintaining it forever
        • unless you want to make a breaking change later and issue a new major release
  • non-negative integers, and MUST NOT contain leading zeroes
  • Each element MUST increase numerically.
  • Once a versioned package has been released, the contents of that version MUST NOT be modified
    • crates.io enforces this for
      • you can pull a version, but you can't replace it
  • Motivation
    • you probably do something close to this already. The problem is that “close” isn’t good enough.
      • Without compliance to some sort of formal specification, version numbers are essentially useless for dependency management.
  • all you need to do to start using Semantic Versioning is to declare that you are doing so and then follow the rules. Link to this website from your README so others know the rules and can benefit from them.
  • FAQ
    • How should I deal with revisions in the 0.y.z initial development phase?
      • start your initial development release at 0.1.0
    • How do I know when to release 1.0.0?
      • If your software is being used in production, it should probably already be 1.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0
      • If you’re worrying a lot about backward compatibility, you should probably already be 1.0.0.
    • As soon as you realize that you’ve broken the Semantic Versioning spec, fix the problem and release a new minor version that corrects the problem and restores backward compatibility
    • What should I do if I update my own dependencies without changing the public API?
      • Determining whether the change is a patch level or minor level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality.