Hi Stephen,
I think there are two separate topics that are related, but aren't
necessarily tied together in such a way where a solution needs to tackle
both. There is the release tagging, and then there is the semantic
versioning.
*Release Tagging*
The initial question I have regarding this is why would it be problematic
to stop having naked version number tags? While using a "go/" prefix would
somewhat clarify *which* tag to use from the perspective of using the
driver, I would think that the question of *why* multiple tags exist would
still be an unanswered question.
I do not have the full scope here to know what implications removing naked
tagging versions would have, but I think it would be a rather low impact
change to start prefixing it with a "v" and have that be the standard going
forward. It seems preferable as it aligns with the current paradigm of
having the versioning be the single source of simplicity, which is already
currently done at the expense of semver practices in various languages.
Also, as an important note, if it is decided to have the "go/" prefix, the
"v" prefix must still exist, i.e. "go/v3.5.3".
*Go Semver*
The people that work on Golang like to enforce the way their tools are
used, which unfortunately can sometimes not align with how people want to
use it in the real world. It works pretty well for purely code packages,
but can lead to issues with "products", as we can see with TinkerPop, where
we want to use the versioning to indicate other things.
By their rules:
- Major versioning is the only time where people upgrading from an older
version should expect their current code to no longer compile and/or work
(what Go Semver says TinkerPop is and should use)
- Something to note here is Golang considers different major versions
of a package to be a separate package. Since we are starting on v3.x, the
references for using our package will become:
- go get github.com/apache/tinkerpop/gremlin-go/v3
- import "go get github.com/apache/tinkerpop/gremlin-go/v3/driver"
- Minor versions are when people upgrading from older versions should
expect everything to work, but people can't downgrade to a lower minor
version and expect their code to compile and/or work (what TinkerPop uses)
- Patch versions the API doesn't change, and code should be expected to
be compile in both a forward and backwards compatible way, but
functionality may be affected due to unexpected bugs in the package
If we go with our current approach, we get the following pros and cons
*Pros:*
- It has a functional workaround, where the user specifies the exact
version of 3.5 or 3.6 they want to use in their package
- The simplicity of the Gremlin version matching the package version
continues
*Cons:*
- The package has a suffix of "v3" which draws emphasis on it, when the
real emphasis should include the .5 or .6
- Someone has to go to the TinkerPop Github to manually find what the
latest release of their version to use
- People who are used to Go but are new to Gremlin probably won't any of
what we're doing with versioning very much
On Thu, Mar 31, 2022 at 6:48 AM Stephen Mallette <[email protected]>
wrote:
> I was reading a bit about best practices for go versioning and how it
> aligns to our release practices. To release a go module you simply tag the
> git repo with a "v" prefixed 3 segment version number. I noticed that
> Apache Arrow, which has a go module, use a "go/" prefix in front of their
> release number for go which i think i'd like to copy to make it clear why
> we have a tag with a naked version number and one with a "v" prefix (the
> official apache release for the former and the go convenience release for
> the latter).
>
> Therefore for 3.5.3 we would have the official apache release tag as usual
> of "3.5.3" and the release tag for go of "go/3.5.3-rc1". Note that the
> "-rc1" suffix is our normal pattern for release candidates and it seems
> acceptable to the go ecosystem to use whatever suffix you like there. As we
> release 3.5.3 with 3.6.0 i would expected we'd also do "3.6.0" and
> "go/3.6.0-rc1" tags.
>
> As an aside, past release candidates don't seem to have bumped the pom at
> the version of the release so it remained in -SNAPSHOT. I assume we'd do
> the same here and tag at the commit prior to the pom bump to the actual
> release version.
>
> I do have some concerns about how strongly go documentation seems to like
> semver as our approach to semver is different than most. If any go experts
> care to share thoughts on any of what I've written here, it would be
> helpful.
>
--
*Simon Zhao*
Software Developer
Bit Quill Technologies Inc.
Direct: 604-728-6911 | [email protected] <[email protected]>
https://www.bitquilltech.com
This email message is for the sole use of the intended recipient(s) and may
contain confidential and privileged information. Any unauthorized review,
use, disclosure, or distribution is prohibited. If you are not the
intended recipient, please contact the sender by reply email and destroy
all copies of the original message. Thank you.
