Updated the docs: https://github.com/apache/tinkerpop/commit/5e2f0aeea9b898cc6382e65e838f1eaa14c34541
Didn't write anything specific to the release process though. I think that will need to be written as we go about doing the first type of this release. Ultimately, I think we would still need to release source for a PATCH version and vote on that. We can then offer a convenience binary just for the driver/client we fixed. The process is slightly abridged, but it will be easier to determine what can be cut out when we actually have to go through and do it. On Fri, Oct 29, 2021 at 7:19 AM Stephen Mallette <[email protected]> wrote: > Divij, yes that is correct. You wrote it more nicely than I did. I will > probably lift your words into the dev docs. > > Florian, thanks for offering that information. I wasn't aware of that > trouble with .NET. I don't really hate that we would have to start the > fourth digit with a "1". I don't think I even mind if each GLV needs a > different 4th place way of doing things because each would release at its > own pace anyway. Release 3.5.2.1 of .NET won't be built from the same > commit as 3.5.2.1 of Javascript. For consistency's sake, perhaps we just > always start with "1" though, assuming there is no problem doing that for > other languages. > > > > > > On Fri, Oct 29, 2021 at 6:56 AM Florian Hockmann <[email protected]> > wrote: > >> I don't have a strong opinion in general in favor or against separate >> versioning and releases for clients, as long as we don't increase the >> required effort to test & release everything much which Stephen already >> mentioned, but I just want to mention that version numbers with 4 parts can >> be problematic for some platforms. >> We had the same idea for versioning for clients of JanusGraph which is >> why I looked into how versions with 4 parts are supported for different >> platforms and it is at least problematic for .NET: >> >> https://github.com/NuGet/Home/issues/7376 >> >> NuGet will for example ignore the fourth part if it's 0 so "3.6.0.0" will >> become "3.6.0". I think that's confusing if we end up with a version >> history such as: >> 3.5.3.2 >> 3.6.0 >> 3.6.0.1 >> 3.6.1 >> 3.6.1.1 >> >> That would be a reason I see against the 4 part versioning scheme, >> although we could of course still adopt it only for some GLVs. >> >> -----Ursprüngliche Nachricht----- >> Von: Divij Vaidya <[email protected]> >> Gesendet: Freitag, 29. Oktober 2021 11:12 >> An: [email protected] >> Betreff: Re: [DISCUSS] Separate versioning and release cycle for clients >> >> Stephen, >> >> Your proposal for E.X.Y.Z sounds good to me. To clarify that we are on >> the same page, let me re-iterate the versioning and release process: >> >> 1. Z is reserved for urgent upgrades such as security patches or major >> bug fixes. >> 2. A client with a specific E.X.Y will be backward compatible with user >> application code written for E.X.Y. >> 3. A client with specific E.X will be backward compatible with the E.X >> version of the server. >> >> Release: >> 1. Clients (may) follow a different release cycle than server which >> implies it is possible to have Java client v3.4.14 released without having >> 3.4.14 release for server or other components. >> 2. E.X.Y will be a release tag specific to the client e.g. 3.4.14-Java. A >> separate branch would be created from the release tag on demand if new >> patches need to be applied to increment Z (which should be rare). >> 3. E.X.Y version of a server will use the latest E.X.latestY version of >> the client for integration testing. >> >> Sounds right? >> >> Divij Vaidya >> >> >> >> On Tue, Oct 12, 2021 at 2:10 PM Stephen Mallette <[email protected]> >> wrote: >> >> > Just wanted to revive this thread a bit: >> > >> > Divij, did you have any thoughts on my suggestions? >> > >> > Dave, I'm coming around to that way of thinking but feel a bit blocked >> > by at least two points. How would we structure things in a separate >> > repository if we were to do that, keeping in mind that: >> > >> > 1. You can't really test the code without Gremlin Server and you're >> > not typically working off of a particular static version of Gremlin >> > Server but from whatever is most current in the git repo for a >> particular branch. >> > 2. The current testing model that builds off the grammar yields us >> > round-trip testing in a single mvn clean install. With that command we >> > parse the documentation and all the feature files for Gremlin, run >> > them through the translators, which generates a Gremlin test file in >> > whatever the native language is, which then is compiled/evaluated >> > natively during the test phase validating both the translation of all >> > that Gremlin as well as the execution of all that Gremlin. >> > >> > We'd need to come up with a way to not give up too much of that >> > convenience and testing if we were to spin out to other repositories. >> > Another alternative that could be considered would be to retain the >> > single repository but restructure it somehow to be a bit easier to >> consume. >> > Potentially this could exclude the maven integration, but we'd still >> > need to satisfy items 1/2 above somehow. >> > >> > On Fri, Oct 1, 2021 at 10:34 AM Dave Bechberger <[email protected]> >> > wrote: >> > >> > > While I am not suggesting we do this the advantage of making >> > > separate repos is that it becomes much less daunting for newcomers to >> contribute. >> > > Right now it is a big beast with tons of projects that make it >> > > difficult >> > to >> > > know where to begin. >> > > >> > > Dave Bechberger >> > > >> > > >> > > > On Sep 28, 2021, at 4:07 AM, Stephen Mallette >> > > > <[email protected]> >> > > wrote: >> > > > >> > > > I agree we have a pain point here. gremlin-scala and Ogre have >> > > > solved >> > > this >> > > > problem by adding a 4th version number. you would therefore have >> > E.X.Y.Z >> > > > where the "E" is the TinkerPop version epoch (i.e. the "3") and >> > > > then >> > the >> > > > X.Y.Z could move as you say. Some issues that would need to be >> > addressed >> > > > come to mind: >> > > > >> > > > + I suspect this sort of change would alter our branching strategy >> > > > + a >> > bit. >> > > > We'd need one branch per "Y" per language. I suppose those would >> > > > just >> > be >> > > > created as needed from the release tags. >> > > > + we would need to come up with a different release tag strategy >> > > > + as >> > well, >> > > > where we prefixed/suffix the version with the language for the tag >> > name. >> > > > + i assume the Java libraries outside of gremlin-driver retain the >> > > standard >> > > > 3 digit version and we'd have just E.X.Y for them >> > > > + under this model where gremlin-driver is more separated in it's >> > > release, >> > > > i'm not sure what that means for the dependency tree of >> gremlin-server. >> > > > gremlin-server depends on gremlin-driver (for serializers mostly i >> > > think). >> > > > maybe that's a non-issue as any 4-digit Z change in the >> > > > gremlin-driver would end up being merged through (in some fashion) >> > > > to the latest gremlin-server 3-digit Z. >> > > > + afaik, there are no troubles with having a child pom with a >> > > > + different >> > > > <version> from the parent, but we'd have to confirm that. >> > > > >> > > > You didn't suggest it, but I'd just make the point that I'd be >> > > > against breaking up the project into multiple repositories at this >> > > > time. We >> > have >> > > > too much good automation, test integration, etc. to let all that go. >> > > > >> > > > >> > > >> On Mon, Sep 27, 2021 at 11:29 AM Divij Vaidya < >> > [email protected]> >> > > >> wrote: >> > > >> >> > > >> Hello all >> > > >> >> > > >> *Summary* >> > > >> I would like to propose that we start releasing clients/drivers >> > > >> with >> > > their >> > > >> own versioning separate from the overall TinkerPop release. >> > > >> Separate release cycles and different versioning schemes for >> > > >> clients will lead >> > to >> > > >> faster release iterations. >> > > >> >> > > >> >> > > >> *Details*Currently, TinkerPop is released as one software >> > > >> including >> > the >> > > >> clients, the query engine, the server and other associated >> components. >> > > This >> > > >> boxed versioning ensures that all artifacts bundled in a release >> > > >> are compatible with each other. This is a good approach with an >> > > >> eye >> > towards >> > > >> maintaining version parity and making it easier for users to get >> > started >> > > >> with using TinkerPop. However, some recent changes in the client >> > > >> have surfaced problems with this approach. >> > > >> >> > > >> >> > > >> *Terminology*If a version is X.Y.Z, X is referred to as the major >> > > version >> > > >> number, Y is the minor version number and Z is the micro version >> > number. >> > > >> >> > > >> *Problem:* >> > > >> The problem with the above versioning arises when newer clients >> > > >> are >> > > still >> > > >> compatible with older TinkerPop servers, but there is a change in >> > > >> application facing contract. This makes them >> > > >> backward-in-compatible >> > with >> > > >> the existing code in user application. As per current release >> > > >> policy, >> > we >> > > >> would wait for the next "minor version" change to release the >> > > >> newer >> > > version >> > > >> of the client with a modified contract. The "minor version" >> > > >> change characterizes breaking changes in the Gremlin language >> > > >> semantics or >> > > server >> > > >> APIs. Due to this coupling between clients and server release, an >> > > >> application facing contract change in the client will not land in >> > > >> the >> > > hands >> > > >> of the user until overall TinkerPop's minor version is changed. >> > > >> >> > > >> As an example, PR-1479 >> > > >> <https://github.com/apache/tinkerpop/pull/1479 >> > > >> > > and >> > > >> PR-1465 <https://github.com/apache/tinkerpop/pull/1465> modify >> > > >> the application facing contract for the Java client. One of them >> > > >> changes >> > the >> > > >> exception thrown from client APIs and the other one deprecated a >> > > >> configuration. Ideally, I would have liked to see them released >> > > >> as >> > 3.6.x >> > > >> (current stable versions are 3.5.x and 3.4.x) ASAP to land these >> > > changes in >> > > >> the hands of users. >> > > >> >> > > >> >> > > >> *Proposal:*Clients should follow their own versioning scheme and >> > > separate >> > > >> release cycle. It is possible for each language client to be on a >> > > different >> > > >> minor version at any given time e.g. the latest release of python >> > could >> > > be >> > > >> 3.4 and for Java it could be 3.7. >> > > >> >> > > >> Proposed versioning contract: >> > > >> 1. Every client with the 3.* version will work with the 3.* >> > > >> version of >> > > the >> > > >> TinkerPop server. >> > > >> 2. Every 3.A.* (where * is a placeholder for micro version >> > > >> increase) version of a client will work with user application >> > > >> code written with >> > a >> > > >> contract for 3.A clients. Such micro version bumps are reserved >> > > >> for security patches or critical bug fixes. >> > > >> 3. Whenever language semantics or results for the language >> > > >> change, it should be a true major version increase i.e. server >> > > >> version moves to >> > > 4.x. >> > > >> >> > > >> *Alternative proposal (not preferred):* Alternatively, we can >> > > >> increment the major version whenever a breaking change occurs >> > > >> across any TinkerPop component. This is not preferred >> > > since >> > > >> this mechanism doesn't dis-ambiguate what component has broken >> > > >> the contract. As an example, for some users it might be >> > > >> acceptable to >> > > upgrade >> > > >> to the new client's contract with their application but they >> > > >> might not >> > > want >> > > >> to pick up the changes in the server associated with that upgrade. >> > > >> >> > > >> Thoughts? >> > > >> >> > > >> Regards, >> > > >> Divij Vaidya >> > > >> >> > > >> > >> >>
