How to support more than one API version?

[tomas-mraz]

Hi Max and Randall,
I would like to open the topic "maintain two major versions" to discuss. I mean for Vulkan 1.1 and 1.3.
I dig around versioning schema a little bit.
The tricky part is the heavy focus of Go on a module's major versions like v1 ... v2 ... v3 ... so the difference between 1.1 and 1.3 simply isn't enough. (I tried and end up with "has malformed module path")

1/ We can do the branch v1 for Vulkan 1.1 with tags v1.0.0+ and
make master for Vulkan 1.3 with tags v3.0.0+.
Import ...vulkan-go/vulkan get data by tags from "v1" branche.
Import ...vulkan-go/vulkan/v3 get data by tags from master (as "v3" in case "v4" come).

2/ The second approach is to just add the directory "v3" in the existing module in the master branch. Make there a second go.mod with path ...vulkan-go/vulkan/v3.
So import ...vulkan-go/vulkan is the same and import ...vulkan-go/vulkan/v3 actually means "path with folder v3".
It is a little bit messy because all files are together and tags should be v1.0.0+ and v3.0.0+ in the same branch depending on changes to publics. It is a backward-compatible solution (in case some app can't handle branches).

These two solutions can't make "visible version" sync "module 1.3 -> Vulkan 1.3" (for example Vulkan 2.0 could be module v4)
As long as I understand there are no publication changes without a tag (even "latest" just detects only the latest tag).
So it looks like no more riding on the last commit :-)

3/ The alternative is "GOPATH mode" which seems like "no tags, all in one repo, just longer path in git and module's name" ... good old days.

Interesting sources ...
https://go.dev/blog/v2-go-modules
https://github.com/golang/go/wiki/Modules#releasing-modules-v2-or-higher

My personal preferences are, 1 the best ... 3 I can live with that ... 2 ohh noo
I can't rule out that I didn't miss something.

[xlab]

Import ...vulkan-go/vulkan get data by tags from "v1" branche.
Import ...vulkan-go/vulkan/v3 get data by tags from master (as "v3" in case "v4" come).

I see this as the only reasonable path forward, very compatible with current industry standards in Go :)
The only thing to care about is compatibility between versions, I assume we can safely do following:

• 1.1 -> v1 (no suffix in repo path)
• 1.2 -> v2
• 1.3 -> v3
• etc

I assume it works since Vulkan 1.1.17 would be compatible with any 1.1.x other versions, 1.2.17 with 1.2.x etc.

Thanks for the suggestion!

[tomas-mraz]

@rcoreilly
I checked Go version 1.10 (before the Go Modules system) and when you try ...

go get github.com/vulkan-go/vulkan
go build

then Go take the master repository.

1/ When we

• make branche v1 for Vulkan 1.1
• make branche master for Vulkan 1.3

it will be a breaking change because projects running on Go1.10 get version v3 instead of (actual) v1.

2/ We can

• leave the master as is and make it a "legacy frozen archive" for old Go with BIG WARNING LABEL
• make branche v1 for Vulkan 1.1
• make branche v3 for Vulkan 1.3 and make it default in GitHub

Finally, after projects migrate to Go1.13+ can be master remove.

3/ or

• leave master for Vulkan 1.1
• make branche v3 for Vulkan 1.3 and make it default in GitHub

A little bit confusing that the master does not contain the latest data.

4/ or

• remove master to make old Go unusable and force projects to use Go Modules
• make branche v1 for Vulkan 1.1
• make branche v3 for Vulkan 1.3 and make it default in GitHub

Well ... an unfriendly solution but effective.

[neurlang]

I vote for master, v3 for Vulkan 1.3, and v1 for Vulkan 1. It would be pretty unexpected to clone master and not have vulkan 1.3 on it (if master is the main branch). Thats why I don't like options 2/, 3/.

Regarding option 4/ making old Go unusable is not ok imo. Better make it broken by forcing latest master to old go.

[Jorropo]

You don't actually need to split branches, you can have a v3 sub-folder within the v1 master branch.
Then everything exists in the same branch under different folders.

[tomas-mraz]

We definitely need v3 branch.
Alex, can you create IT, please?

[Jorropo]

I meant to have the import path github.com/vulkan-go/vulkan/v3 you can have a v3 folder in the same branch the current code exists. This allows to have commits and PR which atomically modify both series (if let's say one depend on the other).

You maybe want different branches for organization purpose then yes multiple branches.