Updated

@mikebrow yeah our getting started flow and website makes me cringe a little bit. I added a link, but we really need some help setting up a more unified experience for getting started.

This is also an opportunity to split out some packages into their own repository when it makes sense (this has been proposed for log).

@dmcgowan This doesnt include splitting the api package right? The one which we planned to do via automatic syncing.

The "Where to put packages" section at the end is proposing the layout for packages for the containerd 2.0 release. While this may seem like a large breaking change, it will align with the go module /v2 change we already need to make.

Example package renames required by importers of v2
github.com/containerd/containerd -> github.com/containerd/containerd/v2/client

Oh, just asking; was your intent with those examples to put packages in a v2 subdirectory ? Because there's two "options"

• Use go's invented alternative to git branches; instead of using branches, you copy all the code to a v2 directory, and maintain all code of all versions in a single branch effectively (v2 and v1 live in the same branch, but "v2" contains code for v2.x.x)
• Or, just tag as v2.0.0 but rename the module (and v1 continues to live in the release branches for v1)

The "use a subdirectory" approach was also for compatibility with old dependency tools.

When moving to v2, you're renaming the module, or to put it in other words "v2" and "v1" are completely separate modules, separate projects, no relation whatsoever (their names may just look similar).
And even with the "v2 subdirectory" approach, these are separate modules (who happens to live in tthe same branch).

It's possible to associate them, but in that case it would require aliases to be provided, so v1 must depend on v2, and make the v1 types aliases for v2.

package foo // this is "foo" in the v1 module


// Import the v2 module, which will be code that's vendored
// so the vendor directory will have a copy of containerd from
// a v2 tag.
//
// go.mod will have something like:
//
// require github.com/containerd/containerd/v2 v2.0.0-alpha.0
import "github.com/containerd/containerd/v2/foo"

// Hello is the v1 alias for v2.
type Hello = foo.Hello

I created a quick example repository with that situation; look at the commit (and tag) history to get a bit of an idea what the flow was for that.

Perhaps there's other options possible; the biggest challenge is how to match signatures. The alternative could be to have v1 -> v2 adaptor code live in the v2 version (to type-cast v1 types to v2)

And of course I didn't post a link to my example repository; here it is; https://github.com/thaJeztah/mod-migrate

Or, just tag as v2.0.0 but rename the module (and v1 continues to live in the release branches for v1)

Was the approach I was thinking based on the previous attempt to rename the module. We already have release branches for maintaining the "v1" module. My understanding is there is no clean way to avoid "/v2" in our import paths once we create the "v2.0.0" tag.

@dcantah Cleaned up the BUILDING and CONTRIBUTING links

I think we can move the v2 module discussion to that PR for now. We know we need it but still figuring out the how.

Ah, yes, sorry for somewhat derailing this PR (and we should / can definitely pick up that discussion elsewhere). I thought for a bit that the intent of that comment was "going forward, create a v2 directory, and put your new things under that".

@dmcgowan and I caught up a bit on Slack, and discussed some of the issues at hand (lots of further brainstorming will still be needed though!)