Branching/vendoring methods Ignition for spec 3.0.0 + 2.x

[ajeddeloh]

Feature Request

Desired Feature

Fedora CoreOS and Container Linux will coexist with different versions of Ignition which will use different Ignition specs. We will need to write tooling to do best-effort translation between them. This means that projects need a way to vendor both versions at the same time.

With the first release of spec 3.0.0 we plan to bump the Ignition version to 1.0.0 and declare API stability.

Since go imports based on repo location (i.e. github.com/coreos/ignition) and doesn't support a way to specify tags in the import path we need a way of having a different import paths for the branches.

The go modules proposal would help, but unfortunately doesn't include the major version in the import path for v0 and v1.

There's also gopkg.in which redirects urls in the form gopkg.in/user/project.vX to github.com/user/project on branch / tag vX, except only the major version is used and it doesn't appear to allow specifying a more granular version. Glide breaks if you specify a gopkg.in url and a version.

Proposals:

1. Don't branch. Rework Ignition to have two code paths in the same binary. Switch which path we use based on version. This is less clean and means we need to carry a bunch of extra logic in both FCOS and CL.
2. Don't branch, fork the 2.x codebase, keeping coreos/ignition for 3.x and creating something like coreos/ignition2x. This is by far the simplest for vendoring but would be confusing for external contributors and would mean duplicating work across repos (rather than branches).
3. Branch Ignition and have a spec2x branch and keep master for 3.x development. Declare API stability for the current codebase (spec 2.x) and make that v1, declare master (spec 3.x) as v2. This allows go modules to be used correctly. Switch to go modules on all projects vendoring Ignition.
4. Branch Ignition and have a spec2x branch and keep master for 3.x development. Manually vendor the spec2x branch to a different path. Could also use GOPATH mangling (@darkmuggle had an idea around this)

I'm leaning towards proposal 3.

cc @lucab @bgilbert

[dustymabe]

My opinion doesn't count for much here, but 3/4 seem the most sane.

Are there projects vendoring ignition that we don't know about? i.e. consumers that we don't control that would be affected by #3 ?

[ajeddeloh]

One's I know of:

• clct
• mantle
• openshift
• maybe tectonic?

I don't think 3 should greatly impact external users, if anything it's better if they have a more stable api. I do worry about what we do if we need to break api compat on the spec2x branch since we'd have already taken the v2.x.y version for spec 3.x.

[bgilbert]

Matchbox also vendors Ignition. Probably any tool that supports Ignition and is written in Go would want to do the same.

[ajeddeloh]

Oh there's also terraform-provider-ct. I guess we could also skip 1.x entirely. That'd give us room to break compat with the 2.x spec and give us unique import paths.

[ajeddeloh]

Thinking about this more, I think that skipping 1.x makes the most sense. The general plan would be:

• Ignition spec 2.x development happens on the spec2 branch.
• Ignition spec 2.x releases happen with Ignition version v0.x.y. We maintain api stability on the v0.x.y releases
• If we need to break api stability for the spec2 branch, we bump the Ignition version to 1.x.y. If we need to break api stability twice we break semver and do it as a 1.x+1.y. We try to avoid that.
• Ignition spec 3.x+ development happens on master
• Ignition spec 3.x+ releases happen as v2.x.y releases.
• If we need to break api stability for the master branch, we increment the major version, as required by semver.
• Until we have a good release for the spec 3.x work, we version Ignition as v2.0.0-alpha so things can vendor both. TODO: check that vgo doesn't die when it hits an -alpha

Things I like about this plan:

• Respects semver except skipping v1 unless we need to break api stability on the legacy codebase twice (unlikely)
• Lets us use go modules correctly
• We don't need to fork it

Things I don't like:

• We skip v1, which is confusing

Barring objections, I'll do this branching strategy tomorrow.

[bgilbert]

Why would we need a major version bump if we break API on the spec2 branch? Semver doesn't require it for 0.x releases, and we haven't done that with previous breaks.

[ajeddeloh]

We don't need to but at this point I think the api is pretty stable (we haven't broken it in a while). I'm fine with just sticking to 0.x though.

[bgilbert]

Yeah, I wouldn't expect any breaks at this point. I was just surprised by the proposed special handling.

[ajeddeloh]

We can also deal with that break if we encounter it

[ajeddeloh]

Closed now that we're branched. Ignition 3.x development will happen on master and Ignition 2.x development will happen on spec2x.