Encouragements to get past v1.0.0's stress

Preamble

The golang dep tool is planned to eventually become the official Go package management tool. Sam Boyer and Carolyn Van Slyck gave great talks (they are on YT) at GopherCon 2017. dep leverages semantic versioning as defined by semver.

Semver is very simple: given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.
  • Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

Issue

As a project maintainer myself, releasing the Version 1 of a project is something that is very stressful and Take the Matter Seriously. It implies a level of quality, professionalism and success that is often very far away from the maintainer’s vision and thus many projects get stuck into v0.x.y for years.

On the other hand, having a clear versioning scheme is valuable for users, as it helps conveying expectations when upgrading caddy as a client. In fact, having a versioning scheme frees the maintainer’s mind to do backward incompatible change, because then they have a tool to formally communicate this fact by bumping the major version number.

Caddy roadmap lists many show stopper that I personally consider long term features, that inhibit bumping the major version within the next years, leading an impossibility to leverage the semver versioning scheme.

Request

I kindly request to 3 things:

  • Reword the roadmap as Feature Complete instead of v1.0, where the feature complete version may be v10, we don’t know.
  • Formally define the compatibility guarantees. We discussed over DM: Caddyfile, CLI tool but plugins are excluded.
  • Start using the semver versioning scheme today.
    • So when a breaking change occurs, MAJOR is inconditionally bumped.

This means as soon there’s a non backward compatible Caddyfile change, the next release will be v1.0.0. It may feel odd, but it’s for the better for everyone. FTR, Chrome is releasing v60 now. :slight_smile:

Thanks!

1 Like

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. :slight_smile:

I’m relieved to know that you understand the stress of a 1.0 release. :sweat_smile: 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. :slight_smile: 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.)

1 Like

Thanks Matt for the thoughtful response.

In my installations, auto-update will not work since the caddy process doesn’t have write access to its own executable, via systemd restrictions. Also people using Caddy in a docker image will likely want to manage deployments by themselves and not want auto-updates. So for my specific use case, auto-update is not valuable but I understand the desire.

I’m the kind of person who prefer to build locally and as soon as Caddy switches its own vendoring to dep, I’ll probably revert back to building Caddy locally instead of downloading from the build server. But I know I’m not the target user. :slight_smile:

So I guess what I’m saying is maybe to focus more on the tests ensuring stability guarantee? I see this more as a real showstopper for a semver based versioning, where auto-update is really a feature that depends on semver, IMHO.

To be clear, it’s not “do this!” message. I’m on a quest to understand why projects get stuck in v0.x.y and your reply is valuable insight.

Thanks!


For posterity, adding links I couldn’t in the preamble above:

The golang dep tool is planned to eventually become the official Go package management tool. Sam Boyer and Carolyn Van Slyck gave great talks (Sam, Carolyn) at GopherCon 2017. dep leverages semantic versioning as defined by semver.

1 Like

Good point; I’m hoping that when we get to this point, we can have a service file and official distro packages that will take care of this.

They can turn them off. :slight_smile:

What’ll be required for this? We already use vendor. What’s involved in switching to dep if it gets added to the official Go toolchain?

In the meantime, I’m quite looking forward to the day when we have our suite of tests in place. It’ll be a good day.