Re: [DISCUSS] Individual Versioning decision for GLV libraries

Debasish Kanhar <d.k...@...>

I meant it in following sense. We go forward with releasing first version which will be tagged as 1.0.0

Now, this would be our current set of features, and as and when bugs are found out, a new patch release will be planned. Lets say some bug fixes leads us to release 1.0.1, then 1.0.2, then 1.0.3 and so on. Thus no we have a line of releases corresponding to patch version which needs to be maintained. I would suggest here just maintaining the latest in line, i.e. if 1.0.2 is out, then 1.0.1 and 1.0.0 won't be activly maintained.

As for minor version bump, let us say that we added a new feature named Schema management. Since it is a huge feature in itself, everything won't be added in single go. Let us say, we release the feature "Schema Management" in between 1.0.2 and 1.0.3 releases. Since it is a new feature, the version which will be released corresponding to the feature will involve a bump in minor version. Since last stable patch release was 1.0.2, hence the new minor release will be tagged 1.1.0 and will include all patch fixes of 1.0.2.
Now, we have 2 separate stable releases, one is 1.1.0 and other will be 1.0.2. All the patches related to Schema management will go into 1.1.x series, i.e. new release named 1.1.1, 1.1.2, 1.1.3 and so on will be released. All patches for non schema library will go into 1.0.x series, i.e. 1.0.3, 1.0.4, 1.0.5 and so on will be released. At end of release, we now have 2 separate versions which need to be actively maintained. Latest in line of 1.0.x series and latest in line of 1.1.x series.

Once another feature is introduced which brings in bump in minor version, let us say new Geoshapes, we will move to 1.2.x series of versions with their corresponding Patch releases. 1.2.x series will contain the latest stable version of 1.1.x series and new features will be added on top of it. Once 1.2.x series are out, then we will stop actively maintaining 1.1.x series, and all corresponding Patch releases moves to 1.2.x series now.

As for huge code breaking changes, like TP version change of GraphSON change, we will just bump the major version number which would be in sync with latest in line of 1.x.y series and 1.0.x series.

Thus, at end of day, we are actively maintaining 3 versions parallely.

One would be latest in line of 1.0.x version, which would be the naked library with least features and their bugs fixed.
Second would be latest in line of 1.x.y version which contains the recent feature added, like either Schema management, GeoShapes etc along with their corresponding bugs fixed.
Third would be, though not required to actively maintain those will be those versions which had change in TP or GraphSON, so that when me merge the feature releases upstream (from patch and minor to major fix branch), we can easily check for conflicts, and will need to maintain only those where conflicts arise.

Let us consider 1.2.2 contains all the recent library with all new features like Schema and Geoshapes added. We will just need to bump TP version for new JanusGraph 0.4.0 and that goes into 2.0.0. All the bug fixes due to conflicts will go into 2.0.x line of releaes, while any new feature would require first creating those features in minor release for older stable TP, like 1.3.0 released, and then those changes are merged upstream into 2.0.0 to form 2.1.0 release. This way once a new feature is added, it gets automatically also added to older versions of library thus working with older version of JanusGraph too.

I hope I was clear on maintainability aspect too, but I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.


On Tuesday, 2 October 2018 18:39:49 UTC+5:30, Florian Hockmann wrote:
3. But if JanusGraph version is upgraded, we don't necessary need to upgrade the Client unless TinkerPop change happens.

The major version bump will be latest version or minor bump series and patch series + new dependency changes. (Eg: If JanusGraph 0.4.0 comes with TP 3.4, then due to code breaks, we will need to to bump Major version number. Considering that latest release of minor version is 1.1.1 and or patch release is 1.0.2, then 2.0.0 will contain all features of 1.1.1 and 1.0.2 along with dependency changes)

I don't get what you mean with this. How can the latest minor version be 1.1.1? Minor version just means the second element of the version number which would be '2' in the version 1.2.3. My proposal was simply to employ semantic versioning. But you're right in general that an update of TinkerPop to 3.4.0 could break things for the client libraries and therefore require a major version bump instead of just a minor version bump.

In general, I can't quite follow what you propose regarding actively maintained branches. How is the versioning related to the number of branches we have to maintain?

Am Dienstag, 2. Oktober 2018 12:34:54 UTC+2 schrieb Debasish Kanhar:
Hi Florian,

Okay, thanks for pointing that out, and I do see few issues with my idea, as in inde[endently bumping major and minor versions of clients by itself without upgrade to JanusGraph is difficult.

At same time I like your idea a lot better but a few issues still remain which adds extra level of complexity and maintainabiliy.

Correct me if my understanding is wrong, (I'm in favour of starting version numbers from 1.0.0 as that seems lot cleaner ;-) )

1. 1.0.0 Supports JanusGraph 0.3.0
2. If Patch is released for same version, we simply bump minor version to 1.0.1.
3. But if JanusGraph version is upgraded, we don't necessary need to upgrade the Client unless TinkerPop change happens. Like JanusGraph 0.3.1 will still use TP 3.3.3 and hence clients of JG 0.3.0 will work with JG 0.3.1 also. So we don't need to release another version of client with bump in patch number just because to sync with bump in JanusGraph patch version upgrade.
4. If a new feature is released for client, let us say schema management, it leads to bump in minor version number, and will be in line with recent patch. i.e. 1.0.1 (Latest patch in line of 1.0) gets merged with recent bump of minor version, (i.e. 1.1.0 will have all features of 1.0.1 + the new feature being released) thus reducing number of versions to be maintained.
5. If any of JanusGraph versions brings in a major change like TinkerPop version change or GraphSON version change, or similar change which will break the library, then we bump the Major Version number. The major version bump will be latest version or minor bump series and patch series + new dependency changes. (Eg: If JanusGraph 0.4.0 comes with TP 3.4, then due to code breaks, we will need to to bump Major version number. Considering that latest release of minor version is 1.1.1 and or patch release is 1.0.2, then 2.0.0 will contain all features of 1.1.1 and 1.0.2 along with dependency changes)

The plus I see with this is, we will need to just actively maintain 2 branches, latest in line of minor and latest in line of patch releases. In this case, 1.1.1 and 1.0.2. Since TinkerPop version change doesn't require additional changes except changing the dependency, the latest in major release line will also be maintained, but requires less work to maintain, and hence helps in maintaing as many major version branches.

Also, if the major version change did bring any major breaking changes (like in case of GraphSON), then either a new version is released by bumping patch number of minor version depending on the type of new feature the bump brings in.

What do you think? A mix of both of our ideas I think :-D

On Monday, 1 October 2018 18:10:44 UTC+5:30, Florian Hockmann wrote:
Thanks for getting the discussion on this topic started!

One disadvantage I see with your proposal is that those version numbers imply semantic versioning but they prevent the libraries from making any changes except for patches independently of the main project as they have to wait for a version bump of JanusGraph's minor or major version before they can bump their minor or major version.

Therefore, I would like to propose that the libraries simply use semantic versioning. That would look like this:

1st release of JanusGraph-Python will be 0.0.1 and target JanusGraph 0.3.0.

The version number for the next release depends on the nature of the included changes:
  1. A patch release results in 0.0.2.
  2. Added functionality requires a minor version bump, so: 0.1.0.
  3. A breaking change bumps the major version number: 1.0.0. (Although versions pre 1.0.0 might still only bump the minor version and only go to 1.0.0 to convey a certain stability of the library.)
  4. Compatibility with a newer JanusGraph version bumps the equivalent version number: Supporting JanusGraph 0.4.0 would result in 0.1.0, whereas supporting JanusGraph 0.3.1 only results in 0.0.2.
The only downside I see with semantic versioning for the libraries is that they need to convey the supported JanusGraph version through another way, but that also seems to be necessary with your method as it's not clear just from a version number like 1.0.0 which JanusGraph version is supported. However, with pure semantic versioning we gain the increased flexibility we wanted to get with the independent versioning of those libraries.

What do you think?

Am Freitag, 28. September 2018 22:56:17 UTC+2 schrieb Debasish Kanhar:
Hi All,

A few days back, Florian had started a Discuss thread regarding how should we version the upcoming GLV libraries for Python and DotNet. After discussions and lazy consensus it felt like we should go forward with independent version numbers for the GLV libraries than the official JanusGraph.

Hence, coming back the main question then remains is even though independent how do we version the GLV libraries.

I've been following the following version semantics and would like to propose the same.

The GLV library will follow x.y.z version number where each are described as follows:
x: Corresponds to a particular JanusGraph major release version.
y: Corresponds to a particular JanusGraph minor release version
z: Corresponds to the path release for GLV library in itself.

For example, since we are starting to support begining JanusGraph 0.3.0, the following set of versions will be followed according to above proposed rule.

JanusGraph 0.3.0 : JanusGraph-Py 1.0.0
JanusGraph 0.3.0 : JanusGraph-Py 1.0.z [For all patches which are compatible with drivers for JanusGraph 0.3.0]

JanusGraph 0.3.1 : JanusGraph-Py 1.1.0 [Notice y change, because there was minor version change in JanusGraph]
JanusGraph 0.3.1 : JanusGraph-Py 1.1.z [For all patches for same JanusGraph version]

When JanusGraph bumps by Major version change like lets say 0.4.0,

JanusGraph 0.4.0 JanusGraph-Py 2.0.z
JanusGraph 0.4.1 JanusGraph-Py 2.1.z

And so on. The above rule helps in maintaining release plan for GLV libraries separately than JanusGraph in itself, and at the same time brings down a bit of commonality in bumps across major/minor version changes of JanusGraph and its Clients.

I'm still open to other ideas, so everyone, all suggestions are welcome.

Debasish K

Join to automatically receive all group messages.