With today’s release of obsidian-export I’m bumping the version number from 0.7.0 to 21.9.0 1 as part of a switch from Semantic Versioning (SemVer) to Calendar Versioning (CalVer).

Rust expects packages to use SemVer for their version numbers, so making a 0.x 2 release initially wasn’t really something I thought about. With support for some features of Obsidian’s custom Markdown dialect missing, a 0.1.0 version number made total sense for a first “non-stable” release.

After a year of working on this project however, I’m convinced that I’m unlikely to release a 1.x that may be considered fully stable any time soon, if ever. While I’m pretty confident the CLI interface (which is how 99% people use it) won’t see significant changes in behavior or argument flags, I’m not willing to make absolute stability guarantees either.

This being my first significant Rust project (and Rust being a complex language with an extensive type system) I have no idea whether some architectural decision made so far is going to cause trouble and require significant internal rewriting to resolve in the future. While I do my best to keep the library side backwards compatible, I wish to have the freedom to make changes on that side as I see fit without worrying about breaking other people’s code. 34

Keeping up continuing 0.x releases for a significant time doesn’t feel useful and I don’t feel compelled to join the ranks of other notable ZeroVer 5 software, so the next best thing seems to be to switch over to CalVer. This will at least give my users an indication of when the software was last released, as opposed to having a magic number which -in their view- just increases arbitrarily.

The version number won’t give any indication about the extent of the changes, but that’s okay; I have no intention of supporting multiple release branches for different major versions, and people can read the changelog (where I already do my best to note anything that could break or behave differently) to determine what’s new or changed in the next version.

  1. YY.MM.MICRO. I wish I could do 21.09.0 (YY.0M.MICRO) instead, but unfortunately that won’t parse as valid SemVer: “invalid leading zero in minor version number for key package.version”. ↩︎

  2. From the SemVer 2.0 spec: “Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.” ↩︎

  3. So far this has only happened once that I know of, in v0.6.0. ↩︎

  4. I’m aware one approach is to split off the library and binary into separate crates, a practice that is somewhat common in the Rust ecosystem. In this case, it doesn’t feel worth the hassle though; both are tied closely together, and I don’t feel like doubling my CI pipelines and release workflows. ↩︎

  5. It might look serious, but this is actually a parody on SemVer and CalVer. Specifically, on software that stays at 0.x for any significant length of time, especially after it’s become well-known and acquired a significant user base depending on it. ↩︎