Hey Marc-Antoine, thanks for elaborating your thoughts and requests here. First, I want to say that I also take versioning pretty seriously, and with Caddy we will do semantic versioning when we get to v1.0, but as the compatibility notice states, before 1.0 there may be breaking changes. I totally benefit from and understand the value of semantic versioning though and am anxious to get to v1.0.
I’m relieved to know that you understand the stress of a 1.0 release. The roadmap on our blog that you linked to is a bit old (over a year). At our launch event in April, we outlined a more precise road to 1.0 with specific features for 0.10, 0.11, and 0.12 trees, assuming the current rate of funding (through what remains of the MOSS award, and then sponsors, etc). These are roughly outlined in our milestones on GitHub. (Many differences from last March. For example, dropping privilege de-escalation as a major feature for 1.0. If it ever happens.)
As to your requests:
- Reword the roadmap as Feature Complete instead of v1.0, where the feature complete version may be v10, we don’t know.
This is a good idea. I like the idea of expediting feature 1.0, however: much needs to happen before we can safely guarantee compatibility and enforce semver. I intend more than just looking at commits and thinking, “No breaking changes here!” - I want tests that prove it. So we’ll need thorough tests at various layers of Caddy: system tests to make sure everything works when wired up, integration tests to make sure different components play well together, and probably more unit tests too. In other words, even if I wanted to, I can’t move Caddy to v1 tomorrow.
- Formally define the compatibility guarantees. We discussed over DM: Caddyfile, CLI tool but plugins are excluded.
Right. I’m thinking that Caddyfile syntax and directive syntax will be covered by the guarantee, and probably the Caddy core CLI. Plugins are definitely excluded, as they do their own versioning. But yes, we will need to formally describe exactly what this covers and what this does not, and give examples.
- Start using the semver versioning scheme today. So when a breaking change occurs, MAJOR is inconditionally bumped.
Even if I felt comfortable with everything else as-is right now, I wouldn’t be able to go to v1 until these verifications are in place.
One other consideration that is absolutely critical related to versioning is how Caddy’s auto-upgrade system will work. We will be enabling this feature by default on all Caddy instances in the somewhat-near-future, as soon as we work out the details of what triggers an automatic upgrade, how they get distributed gradually, and how to handle upgrades across different major versions. (For now I’m intending auto-upgrades to happen only for security releases.) The build server will play an important role here too. Because of its role in distributing Caddy, I need to make sure that release channels are established with the auto-upgrade system in mind before we go to v1. As we move to “stable” releases (although I want to be clear that Caddy is “production-ready” already) with major versions, it becomes imperative to decide how many versions back we will “support”. Right now, I only support the latest release. We could still do that, but with auto-upgrades, will we stop updating v1.x instances with security fixes just because we only support the latest major version (which are never auto-updated, because possible breaking changes)? That seems to defeat the purpose of auto-updates.
In short - we’ll get there. I know it’s a bother to deal with breaking changes right now, but we won’t be in this state for long. And we do list the breaking changes (along with all other significant/notable changes that aren’t breaking) in the change log for every release. But as I said, these are built manually; we don’t have a rigorous system of regression testing in place yet.
We only barely got our automated build server (and release tool) deployed a few months ago in April. Without that, we couldn’t even be having this conversation right now. We’ll get there. Assuming we continue to grow our sponsorships and the project stays funded, I promise it’ll happen.
(Fun fact: The latest commit of the release tool, which I haven’t pushed yet, uses Mark’s semver library to suggest next possible tags when pushing a release; to help guarantee that semver is properly applied.)