I had some experiences with doing this sort of thing for what eventually became github.com/hashicorp/hcl/v2. I have some assorted notes to share about that experience, which I hope will substitute for a more definitive answer to your question "does this sound reasonable?", because I don't feel comfortable giving an answer to *that* except "it depends"!
I will add some context that I was doing most of this when Go v1.11 and then v1.12 were current, and so I'm not sure if all of the exact behavior details I'm saying here remain true in recent Go releases, and also this was a while ago and so I may be misremembering some details. The first thing I learned is that if you name a branch something like "v2" then a go get github.com/hashicorp/hcl/v2@v2 would stop working as soon as there is a tag v2.0.0, because the version selection gives preference to tag-matching before it considers branch matching, and it treats "v2" as a shorthand for v2.0.0. To counter that, I named my temporary development branch "hcl2", which I would then install using go get github.com/hashicorp/hcl/v2@hcl2 when I wanted to get the latest commit from that branch. Separately, it's worth noting that this strategy of making v2 be a change to the root go.mod (adding the /v2 suffix) is one of two options; the other is to put your second version in a v2 subdirectory and keep v1 in the root, effectively maintaining them both together in the same tree. For HCL making v2 live in the root and having v1 continue as a separate maintenance branch felt best because v2 is a revolutionary change rather than just an incremental update, but it does have the important consequence that folks using GOPATH mode can no longer use either version once v2 is in the main branch. (In GOPATH mode, the toolchain can only install from the main branch.) To mitigate that, we ended up waiting a full year after creating the first stable v2 tag from the hcl2 branch before we changed the main branch to track v2 and moved v1 into a "hcl1" maintenance branch. Finally, I want to note that you don't actually really need to create that v2.0.0-alpha tag unless having it tagged is important for documentation purposes. You can see in my examples two paragraphs ago that you can install the v2 module from an arbitrary branch (/v2@hcl2 in my case), which causes go.mod to track a synthetic version number that starts with v2 and includes the git commit id, and thus behaves just like a prerelease version but without the need for an explicit tag. When I was first working on this I found it useful to create a temporary, throwaway repository to play around with in order to see the Go tool's behaviors in each case. While I hope the above is useful in understanding some of the details of how this transition might work for you, I think there's no substitute for rehearsing it to get confidence for what will happen at each step. Indeed, doing that is how I learned the three notes I shared above, prior to following a process like what you described against the real repository. On Wednesday, April 7, 2021 at 4:43:54 PM UTC-7 mar...@gmail.com wrote: > Hi All, > > I need to release a V2 of my module. ( > https://github.com/deepmap/oapi-codegen). I understand what to do on the > Go side in terms of the /v2 suffix and go.mod changes, but I'm a little bit > unclear how this works w.r.t git branches. Yes, I've looked at > https://golang.org/ref/mod#vcs-find > > My plan is to do development in a "v2" branch, which which will > occasionally be rebased onto the "master" branch until that's no longer > feasible, at which point I'll cherry pick or port important commits from > master to v2. > > The v2 branch will start off with an annotated tag named "v2.0.0-alpha". > and will begin to diverge from master, which is tagged with v1.x.x > > When I am ready to release the V2 branch, I plan to do the following. > > Top commit in master becomes a new branch, "v1", and any future V1 bug > fixes go here. > > I will merge the V2 branch into master, and tag it as v2.0.0. > > Does this sounds like a reasonable plan? I would like, for the time being, > for people to be able to work on V1 in master, and eventually master will > become V2 while V1 is a branch. > > My alternative is to create a V1 branch today, and all future work in > master is V2. > > -- Marcin > -- You received this message because you are subscribed to the Google Groups "golang-nuts" group. To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/golang-nuts/64280de7-7832-4ee6-b402-65cacecfaca8n%40googlegroups.com.
