Date   

Re: [DISCUSS] Official JanusGraph docker image repo

andy.r...@...
 

Any idea when this is going to get a release?


On Thursday, August 30, 2018 at 3:56:14 PM UTC+1, Ted Wilmes wrote:
Ok, I moved Mr. Pounds code over into my fork of the new repo and put a "scratch" PR in: https://github.com/JanusGraph/janusgraph-docker/pull/1

Let's move our discussion/feedback on approach over to that PR unless you all think it would be beneficial to continue here on the list.

--Ted

On Monday, August 27, 2018 at 3:11:12 PM UTC-5, Chris Hupman wrote:
I think that makes sense as a starting point. I'm assuming there will be a fair amount of testing, discussions,  and iterations before it gets pushed up as an official image. 

On Monday, August 27, 2018 at 1:05:49 PM UTC-7, Ted Wilmes wrote:
I think I can get to that later this week. I could push Chris' work into a new branch on the new repo and then put a PR in so we could come to some consensus on if that's a good starting point?

On Mon, Aug 27, 2018 at 2:57 PM Chris Hupman <ch...@...> wrote:
One last question, mainly for Expero folks. Is anyone already intending to make the initial commit? I have a conference this week, but can work on this next week if not.

On Monday, August 27, 2018 at 8:07:24 AM UTC-7, Jason Plurad wrote:
https://github.com/JanusGraph/janusgraph-docker is created

On Tuesday, August 21, 2018 at 3:17:00 AM UTC-4, Florian Hockmann wrote:
Yes, +1 for the separate repo.

Am Dienstag, 21. August 2018 03:04:23 UTC+2 schrieb Ted Wilmes:
Hey Chris,
Appreciate the extra stir and yes, I'm in agreement. +1 for a separate repo.

Thanks,
Ted

On Mon, Aug 20, 2018, 3:14 PM Chris Hupman <ch...@...> wrote:
Stirring one more time. Ted and Florian are you guys in favor of the creation of a repo for an official JanusGraph docker image?


On Thursday, August 16, 2018 at 8:19:05 AM UTC-7, Jason Plurad wrote:
+1 for a single janusgraph-docker repo.

Wouldn't you be able to use the directory structure to manage the different flavors of a Docker image that we want to publish to Docker Hub? I wouldn't want to create multiple JanusGraph repos for Docker technology.


On Wednesday, August 15, 2018 at 2:25:32 PM UTC-4, Chris Hupman wrote:
Since we seem to be making repos right now I wanted to stir this up a bit. I think right now would be a good time to make a janusgraph-docker repo for an official Docker image. 

I mainly wanted to ask if a single repo would be adequate. I personally like the approach of a single image defaulting to in-memory so the image can be deployed standalone and then configuring through -e flags at deploy. In one of the PRs it was suggested to default to using es and Cassandra. I am assuming, quite possibly incorrectly,  that would mean throwing es, Cassandra, and JanusGraph in a single container for ease of deploy. If that was the case an additional repo would probably be required. 

Hoping to get some +1s for a consensus on adding a janusgraph-docker repo.

Chris

On Thursday, June 7, 2018 at 12:34:30 AM UTC-7, Florian Hockmann wrote:
what if we included a minimal Docker build as part of the repo for client library testing and then left the separate repo to serve only the purpose of producing official, published Docker images?

That makes perfectly sense to me. Seems to be the best solution overall to me.

Am Mittwoch, 6. Juni 2018 22:05:18 UTC+2 schrieb Ted Wilmes:
Thanks for the responses Chris and Florian. I'm in agreement that we should first discuss the separate repo issue separate from the implementation details. That was my intent, but by including those two links I conflated the two. I would expect either approach we take to go through the usual PR process, or perhaps even another round of discussion. My Alpine base image example isn't a great one, may main point is that for whatever reason, there may be a community desire to support a variety of different configurations for the images (not Janus configs themselves to be clear).

Your point about client library development is a good one. My inclination is to treat the JanusGraph developer Docker environment use case differently than the JanusGraph end-user use cases (user dev & integration testing, production deployment). There would undoubtedly be some overlap, but what if we included a minimal Docker build as part of the repo for client library testing and then left the separate repo to serve only the purpose of producing official, published Docker images?

Thanks,
Ted

On Wednesday, June 6, 2018 at 6:41:50 AM UTC-5, Florian Hockmann wrote:
Hi,

first of all, big thanks for bringing this up again! I'm really looking forward to an official JanusGraph image.

I can think of one advantage of including the Docker images in the main JanusGraph repo: When you want to test a client library like the ones we will probably create for the different languages (I'm currently working on one for .NET) then you need an instance of the server and this should be a version of the server that will be released with the same version number. A JanusGraph docker image would make testing of such a client library much easier but when we put the Dockerfile in another repo then we would only have already published images available in the main repo. So you couldn't test such a client library with a Docker image of the server as it is at that moment in the repo, you would rather have to use an already released version.

A big advantage of a separate repo would be that we could make use of DockerHub's automated builds which can then also include the README.md and the Dockerfile.

One thing I'm wondering about:

potentially supporting a variety of different linux distros including alpine

What's the advantage of having images for other distros than alpine? Having alpine as the base image means that the image will be really small but do users also want a debian based image or something like that?

I haven't looked into the new repo Chris created in detail as I think that we should first only discuss about whether or not a separate repo should be used and I assume that there will be the usual review process afterwards.

Am Dienstag, 5. Juni 2018 22:52:42 UTC+2 schrieb Chris Hupman:
Hello,
I'm regularly using containers for Cassandra and Elasticsearch for my JanusGraph work and I had a couple of thoughts on this. 
  • In pull 700 only janusgraph is being run, in the experoinc repo es, cassandra, and janusgraph are all running in the same container. I personally think JanusGraph only running in-memory by default is the right approach. While an all-in-one is great for development it wouldn't really make sense for a real deployment. 
  • Right now both containers are using JanusGraphFactory(JGF) instead of ConfiguredGraphFactory(CGF). Since this container is for running JanusGraph server I think CGF would make more sense than JGF. 
  • To be more modular and avoid passing as many -e flags it should support multiple gremlin server files through ENVs. 
  • For JGF deployments we should add in a script to bind g = graph.traversal() to improve user experience as referenced in the docs
  • For CGF deployments it would be nice if the container tried to create a template using the configuration parameters it already had access to. 
  • I think it makes sense to house the docker components and tests in a separate repo. With the approach of downloading the release and moving it to /opt/janusgraph it would be easy to run a script afterwards to update the yaml and property files to take ENVs. 
I think this would be great for the overall health of the project and I'm willing to help out with code, docs, and/or testing.

On Tuesday, June 5, 2018 at 9:33:42 AM UTC-7, Ted Wilmes wrote:
Hello,
I wanted to restart a discussion on producing an official JanusGraph Docker image. There is lots of community interest and progress has been made but we're not quite there yet. There is an existing PR [1] that a coworker of mine, Chris Pounds, had been working on. After some brainstorming with Misha Brukman, we were wondering if a change in approach may make sense. Namely, that it might be a good idea to host the artifacts required to maintain Janus docker images separate from the main JanusGraph repo. With that in mind, Chris has recently created this repo: https://github.com/experoinc/janusgraph-images. It's sitting under out GitHub at the moment but is Apache 2 licensed, and if this plan makes sense to folks, we'd just transition it over to the Janus org and put it through the usual PR and approval process. With all that said, I think there are a number of benefits to maintaining the Docker plumbing separate from JanusGraph itself. I would imagine a matrix of different versions and image options at some point, potentially supporting a variety of different linux distros including alpine. Also, it would be nice to be able to version the Docker artifacts separately from JanusGraph so that we can rev them at different speeds. So, first step is I'd like to get some community feedback on this approach and see what folks thought about setting up a separate repo under the Janus org to host the Docker plumbing?

Thanks,
Ted

--
You received this message because you are subscribed to a topic in the Google Groups "JanusGraph developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/janusgraph-dev/V70uVxh9who/unsubscribe.
To unsubscribe from this group and all its topics, send an email to janusgraph-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/d2da37b0-44c1-4c3b-b51b-58e279bdeefa%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "JanusGraph developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/janusgraph-dev/V70uVxh9who/unsubscribe.
To unsubscribe from this group and all its topics, send an email to janusgraph-de...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/1da5c589-aef2-437c-b89e-9064108f0e7c%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [VOTE] JanusGraph 0.2.2 release

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

+1 LGTM.


On Tuesday, 9 October 2018 23:40:24 UTC+5:30, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

Please note that the v0.2.2 tag has been updated. You can refresh your tags with this command:
        git tag -l | xargs git tag -d && git fetch -t

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 12, 2018 at 2:10 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad


Re: [VOTE] JanusGraph 0.2.2 release

Jerry He <jerr...@...>
 

+1

 Downloaded the binary zip. Checked the signature.  Good.
 Unzip it.  Looked at the directories and files.  Good.
 Ran simple transactions and queries against HBase 1.2.6 and Solr 6.3.0.  Good.
Opened graph from version 0.2.1.  Good.
 Started gremlin-server and ran queries against the same backend configuration.  Good.

On Thu, Oct 11, 2018 at 12:04 AM <Jan....@...> wrote:

+1


Von: janusgr...@... <janusgr...@...> im Auftrag von Chris Hupman <chris...@...>
Gesendet: Donnerstag, 11. Oktober 2018 05:57:27
An: JanusGraph developers
Betreff: Re: [VOTE] JanusGraph 0.2.2 release
 
+1

On Tuesday, October 9, 2018 at 11:10:24 AM UTC-7, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

Please note that the v0.2.2 tag has been updated. You can refresh your tags with this command:
        git tag -l | xargs git tag -d && git fetch -t

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 12, 2018 at 2:10 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/09deed28-d5cd-42d7-9f2f-2152ef656b73%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/25676aeda33a4196ba86d39395a7aa88%40gdata.de.
For more options, visit https://groups.google.com/d/optout.


Re: [DISCUSS] Individual Versioning decision for GLV libraries

Florian Hockmann <f...@...>
 

One last note regarding the initial version: I just had a short discussion with Jan Jansen (aka farodin91) about this and he mentioned that an initial version should not be 0.0.1, but 0.1.0 as 0.0.1 would indicate that it is a patch release although there is nothing for it to patch as it's the first version. This is also in line with the recommendation from the SemVer FAQ:

How should I deal with revisions in the 0.y.z initial development phase?

The simplest thing to do is start your initial development release at 0.1.0 and then increment the minor version for each subsequent release.


So, my suggestion is that we use semantic versioning for the libraries and start with 0.1.0.


Am Mittwoch, 10. Oktober 2018 21:51:01 UTC+2 schrieb Florian Hockmann:
Thanks for trying this out with PyPi and yes, you got my suggestion exactly right.

Unfortunately, I think that my suggestion wouldn't even completely work for NuGet like I proposed it earlier, exactly for the reasons you mentioned for PyPi, namely the normalization of version numbers. I didn't know that when I posted my suggestion, but NuGet seems to apply a very similar normalization. The docs state for example that: "Leading zeroes are removed from version numbers" which would also turn 0.3.001 into 0.3.1 and thus making my suggestion basically useless.

What I also didn't know earlier is that NuGet also supports version numbers with four parts which means that we could technically use the approach Stephen suggested and use version numbers like 0.3.0.1. However, four part version numbers are so unusual for NuGet packages that I really had to search before I could find a few packages that use them. I also have the suspicion that NuGet only supports them for some legacy reason and that it isn't the best idea to use such a version number for a new project.
I will try to find out whether using a four part version number has any disadvantages for a NuGet package or whether it is actively discouraged by the NuGet team. I already created an issue with that question 2 days ago and since they don't seem to respond that often to issues, I also just asked this on StackOverflow. Maybe someone on there has some insights on this topic.

Apart from whether it would be possible to use a four part version with NuGet or PyPi, I wonder whether it's a good idea in general. It might be possible for PyPi and NuGet, but semantic versioning is becoming the de-facto standard, or at least SemVer style three part version numbers are. npm for example also expects SemVer style version numbers, so does Rust's package manager Cargo and also the package manager for Swift.
If JanusGraph itself would follow semantic versioning, then we could only copy the major and minor version and use the third part (the patch version) for a library version. Including the third part of JanusGraph's version wouldn't be important as JanusGraph 0.3.1 would be JanusGraph 0.3.0 + bug fixes which wouldn't make any difference for a driver. But since JanusGraph also includes new features in releases like 0.3.1, we can't omit any part of the version number if we want to include that in the version of the libraries.

Sooo, I'm personally coming back to being in favour of simply following SemVer for the drivers which would mean that they start with version 0.0.1. We then only have to communicate to users which version of JanusGraph the driver is compatible with. But we can probably simply include that very prominently in the description of each package which should show up in the web interfaces of the package repositories for most languages.

I don't think that it's important for our decision, but out of interest I checked if and how the .NET drivers of the 10 most popular databases (according to DB-Engines) used the database version in their version:
  • The MySQL driver was the only one that uses exactly the same version (so they also seem to be released together).
  • 3 drivers shared only their major version with their database, namely Oracle, Elasticsearch, and Cassandra.
  • 5 drivers seem to have completely unrelated version numbers.
(The numbers don't add up to 10 as I couldn't find a NuGet package for Microsoft Access.)

Am Mittwoch, 10. Oktober 2018 16:25:37 UTC+2 schrieb Debasish Kanhar:
Everyone, I think Florian's idea can be modified a bit to support Python's PyPi versioning.

If I'm correct, Florian suggested following structure:

X.Y.ZZAA

Where X: JanusGraph majov version number: 0
Y: JanusGraph minor version number: 3 (0.3.x)/ 4 (0.4.x) etc
ZZ: JanusGraph patch version number in 2 digit version appended by 0 if needed. : 01/02/03 .. etc
AA: Library's Patch version numbers, starting with 00

Since PyPi normalizes the version numbers as normal numbers, we can trick it into thinking that the version we are following are valid numbers as follows:

X.Y.ZZAA then becomes X.Y.ZAA
Meaning, we don't append JanusGraph patch version number with additional 0. We just write the version number as it is. If a Path 10 is reached, then .ZAA becomes .ZZAA as follows:

JanusGraph version    Library Version, Patch 1
0.3.9                         0.3.901
0.3.10                       0.3.1001

If we think that we don't have fixed digits for version numbers, well we can think it in way that it is dynamic enough to accomodate our required use cases.

And, in addition to that I would like to propose a rule for Library Patch version numbers (AA) that it starts from 01 and not 00. This is to avoid following scenario:

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.1                          0.3.101                 0.3.101                              0.3.101
0.3.1                          0.3.100                 0.3.1                                  0.3.100

But I think of one drawback with this restricted approach is that, how do we tackle normalization when JanusGraph is on 1st release of a minor version. (0.3.0). In such scenario, following thing will happen with PyPi

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.0                          0.3.001                 0.3.1                                 0.3.001

We lose the information regarding which JanusGraph minor version that it.

Any ideas how do we proceed?


On Monday, 8 October 2018 21:28:37 UTC+5:30, Debasish Kanhar wrote:
Florian, Stephen. Thanks guys for your input. That was really a helpful comment but I was doing quick testing on what Version numbers are supported on PyPi (Where Python libs are hosted).

1. So, It got me wondering, because PyPi doesn't support uploading versions with tags in it. So something like "0.3.0101-beta1" will fail because it contains string which is Invalid.
2. Similarly, I thought will they support 4 digit versioning, and I tried "0.3.0.1" and it worked like a charm and the library got published to PyPi withoug any errors. Great news.
3. Then I tried out Florian's idea, having 3 digit codes, but 3rd one having 4 digits. Hence the analogous "0.3.0001" actually doesn;t get uploaded the way it is expected to. Python normalizes the version number, and hence 0.3.0001 now becomes 0.3.1. Similarly 0.3.0101 now becomes 0.3.101. Now due to this normalization, the Version numbers aren't getting reflected properly to PyPi. Looks like this is a technical drawback.

But looking at your comments, looks like NuGet doesn't support 4 digit SymVer versioning? If such is scenario, I don't know how do we reach a consensus here, as it looks like the version numbers supposed to be working with PyPi won't be working with NuGet or vice versa. 

On Sunday, 7 October 2018 17:22:53 UTC+5:30, Florian Hockmann wrote:

Thanks for your input on this, Stephen! This really got me thinking.


I think in the end it comes down to the question of what is more important for us to communicate to users with the version: Which version of JanusGraph (and therefore implicitly TinkerPop) is supported or whether new features or breaking changes are included in the library itself that are not related to an updated JanusGraph version?

The more I think about this, the more I tend towards primarily communicating the supported JanusGraph version. Once the libraries support all JanusGraph specific predicates and data types, there won’t be many changes to them. The only changes will probably be updated dependencies which is mostly the TinkerPop GLV and those versions will be in line with the TinkerPop version supported by JanusGraph. So, I guess the optimal solution for the library versions would include the supported JanusGraph version. That would also have the advantage that users won’t have to keep track of yet another version and ensure that everything is compatible (the compatibility matrix of JanusGraph is already complicated enough).


Unfortunately, we can’t completely copy the versioning strategy from Ogre as it uses 4 version elements and some package managers (like NuGet) expect SemVer style versions with only 3 elements. We could solve this by taking the JanusGraph version and then extending the third element with a version number for the library itself. So, something like this:


JanusGraph version   Library version
0.3.0                        0.3.0000
0.3.0                        0.3.0001
0.3.1                        0.3.0100
0.4.0                        0.4.0000

The first 2 digits of the third element reflect the third element of the JanusGraph version and the last 2 digits are for the library version. 2 digits are necessary in case JanusGraph reaches a version like 0.3.10 and the same for the library which could reach 0.3.0010.

The .NET Core SDK uses a similar versioning strategy. The only difference is that they only include the major and minor version of the .NET Core runtime as the patch version really only contains patches which is not the case for JanusGraph and TinkerPop. That allows them to include a minor and patch version together in a 3 digit third element of the version.

We could use this versioning when we agree that we only add breaking changes when a new JanusGraph version is out that allows breaking changes (next would be 0.4.0).

So, what do others say? Should we use versions like 0.3.0000?

Am Samstag, 6. Oktober 2018 17:41:18 UTC+2 schrieb Stephen Mallette:
I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-de...@googlegroups.com.
To post to this group, send email to jan...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [VOTE] JanusGraph 0.2.2 release

Jan....@...
 

+1


Von: janusgr...@... <janus...@...> im Auftrag von Chris Hupman <chri...@...>
Gesendet: Donnerstag, 11. Oktober 2018 05:57:27
An: JanusGraph developers
Betreff: Re: [VOTE] JanusGraph 0.2.2 release
 
+1

On Tuesday, October 9, 2018 at 11:10:24 AM UTC-7, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

Please note that the v0.2.2 tag has been updated. You can refresh your tags with this command:
        git tag -l | xargs git tag -d && git fetch -t

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 12, 2018 at 2:10 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-dev+unsu...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/09deed28-d5cd-42d7-9f2f-2152ef656b73%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [VOTE] JanusGraph 0.2.2 release

Chris Hupman <chris...@...>
 

+1


On Tuesday, October 9, 2018 at 11:10:24 AM UTC-7, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

Please note that the v0.2.2 tag has been updated. You can refresh your tags with this command:
        git tag -l | xargs git tag -d && git fetch -t

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 12, 2018 at 2:10 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad


Re: [DISCUSS] Individual Versioning decision for GLV libraries

Florian Hockmann <f...@...>
 

Thanks for trying this out with PyPi and yes, you got my suggestion exactly right.

Unfortunately, I think that my suggestion wouldn't even completely work for NuGet like I proposed it earlier, exactly for the reasons you mentioned for PyPi, namely the normalization of version numbers. I didn't know that when I posted my suggestion, but NuGet seems to apply a very similar normalization. The docs state for example that: "Leading zeroes are removed from version numbers" which would also turn 0.3.001 into 0.3.1 and thus making my suggestion basically useless.

What I also didn't know earlier is that NuGet also supports version numbers with four parts which means that we could technically use the approach Stephen suggested and use version numbers like 0.3.0.1. However, four part version numbers are so unusual for NuGet packages that I really had to search before I could find a few packages that use them. I also have the suspicion that NuGet only supports them for some legacy reason and that it isn't the best idea to use such a version number for a new project.
I will try to find out whether using a four part version number has any disadvantages for a NuGet package or whether it is actively discouraged by the NuGet team. I already created an issue with that question 2 days ago and since they don't seem to respond that often to issues, I also just asked this on StackOverflow. Maybe someone on there has some insights on this topic.

Apart from whether it would be possible to use a four part version with NuGet or PyPi, I wonder whether it's a good idea in general. It might be possible for PyPi and NuGet, but semantic versioning is becoming the de-facto standard, or at least SemVer style three part version numbers are. npm for example also expects SemVer style version numbers, so does Rust's package manager Cargo and also the package manager for Swift.
If JanusGraph itself would follow semantic versioning, then we could only copy the major and minor version and use the third part (the patch version) for a library version. Including the third part of JanusGraph's version wouldn't be important as JanusGraph 0.3.1 would be JanusGraph 0.3.0 + bug fixes which wouldn't make any difference for a driver. But since JanusGraph also includes new features in releases like 0.3.1, we can't omit any part of the version number if we want to include that in the version of the libraries.

Sooo, I'm personally coming back to being in favour of simply following SemVer for the drivers which would mean that they start with version 0.0.1. We then only have to communicate to users which version of JanusGraph the driver is compatible with. But we can probably simply include that very prominently in the description of each package which should show up in the web interfaces of the package repositories for most languages.

I don't think that it's important for our decision, but out of interest I checked if and how the .NET drivers of the 10 most popular databases (according to DB-Engines) used the database version in their version:
  • The MySQL driver was the only one that uses exactly the same version (so they also seem to be released together).
  • 3 drivers shared only their major version with their database, namely Oracle, Elasticsearch, and Cassandra.
  • 5 drivers seem to have completely unrelated version numbers.
(The numbers don't add up to 10 as I couldn't find a NuGet package for Microsoft Access.)

Am Mittwoch, 10. Oktober 2018 16:25:37 UTC+2 schrieb Debasish Kanhar:

Everyone, I think Florian's idea can be modified a bit to support Python's PyPi versioning.

If I'm correct, Florian suggested following structure:

X.Y.ZZAA

Where X: JanusGraph majov version number: 0
Y: JanusGraph minor version number: 3 (0.3.x)/ 4 (0.4.x) etc
ZZ: JanusGraph patch version number in 2 digit version appended by 0 if needed. : 01/02/03 .. etc
AA: Library's Patch version numbers, starting with 00

Since PyPi normalizes the version numbers as normal numbers, we can trick it into thinking that the version we are following are valid numbers as follows:

X.Y.ZZAA then becomes X.Y.ZAA
Meaning, we don't append JanusGraph patch version number with additional 0. We just write the version number as it is. If a Path 10 is reached, then .ZAA becomes .ZZAA as follows:

JanusGraph version    Library Version, Patch 1
0.3.9                         0.3.901
0.3.10                       0.3.1001

If we think that we don't have fixed digits for version numbers, well we can think it in way that it is dynamic enough to accomodate our required use cases.

And, in addition to that I would like to propose a rule for Library Patch version numbers (AA) that it starts from 01 and not 00. This is to avoid following scenario:

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.1                          0.3.101                 0.3.101                              0.3.101
0.3.1                          0.3.100                 0.3.1                                  0.3.100

But I think of one drawback with this restricted approach is that, how do we tackle normalization when JanusGraph is on 1st release of a minor version. (0.3.0). In such scenario, following thing will happen with PyPi

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.0                          0.3.001                 0.3.1                                 0.3.001

We lose the information regarding which JanusGraph minor version that it.

Any ideas how do we proceed?


On Monday, 8 October 2018 21:28:37 UTC+5:30, Debasish Kanhar wrote:
Florian, Stephen. Thanks guys for your input. That was really a helpful comment but I was doing quick testing on what Version numbers are supported on PyPi (Where Python libs are hosted).

1. So, It got me wondering, because PyPi doesn't support uploading versions with tags in it. So something like "0.3.0101-beta1" will fail because it contains string which is Invalid.
2. Similarly, I thought will they support 4 digit versioning, and I tried "0.3.0.1" and it worked like a charm and the library got published to PyPi withoug any errors. Great news.
3. Then I tried out Florian's idea, having 3 digit codes, but 3rd one having 4 digits. Hence the analogous "0.3.0001" actually doesn;t get uploaded the way it is expected to. Python normalizes the version number, and hence 0.3.0001 now becomes 0.3.1. Similarly 0.3.0101 now becomes 0.3.101. Now due to this normalization, the Version numbers aren't getting reflected properly to PyPi. Looks like this is a technical drawback.

But looking at your comments, looks like NuGet doesn't support 4 digit SymVer versioning? If such is scenario, I don't know how do we reach a consensus here, as it looks like the version numbers supposed to be working with PyPi won't be working with NuGet or vice versa. 

On Sunday, 7 October 2018 17:22:53 UTC+5:30, Florian Hockmann wrote:

Thanks for your input on this, Stephen! This really got me thinking.


I think in the end it comes down to the question of what is more important for us to communicate to users with the version: Which version of JanusGraph (and therefore implicitly TinkerPop) is supported or whether new features or breaking changes are included in the library itself that are not related to an updated JanusGraph version?

The more I think about this, the more I tend towards primarily communicating the supported JanusGraph version. Once the libraries support all JanusGraph specific predicates and data types, there won’t be many changes to them. The only changes will probably be updated dependencies which is mostly the TinkerPop GLV and those versions will be in line with the TinkerPop version supported by JanusGraph. So, I guess the optimal solution for the library versions would include the supported JanusGraph version. That would also have the advantage that users won’t have to keep track of yet another version and ensure that everything is compatible (the compatibility matrix of JanusGraph is already complicated enough).


Unfortunately, we can’t completely copy the versioning strategy from Ogre as it uses 4 version elements and some package managers (like NuGet) expect SemVer style versions with only 3 elements. We could solve this by taking the JanusGraph version and then extending the third element with a version number for the library itself. So, something like this:


JanusGraph version   Library version
0.3.0                        0.3.0000
0.3.0                        0.3.0001
0.3.1                        0.3.0100
0.4.0                        0.4.0000

The first 2 digits of the third element reflect the third element of the JanusGraph version and the last 2 digits are for the library version. 2 digits are necessary in case JanusGraph reaches a version like 0.3.10 and the same for the library which could reach 0.3.0010.

The .NET Core SDK uses a similar versioning strategy. The only difference is that they only include the major and minor version of the .NET Core runtime as the patch version really only contains patches which is not the case for JanusGraph and TinkerPop. That allows them to include a minor and patch version together in a 3 digit third element of the version.

We could use this versioning when we agree that we only add breaking changes when a new JanusGraph version is out that allows breaking changes (next would be 0.4.0).

So, what do others say? Should we use versions like 0.3.0000?

Am Samstag, 6. Oktober 2018 17:41:18 UTC+2 schrieb Stephen Mallette:
I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-de...@googlegroups.com.
To post to this group, send email to jan...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [DISCUSS] Individual Versioning decision for GLV libraries

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

Everyone, I think Florian's idea can be modified a bit to support Python's PyPi versioning.

If I'm correct, Florian suggested following structure:

X.Y.ZZAA

Where X: JanusGraph majov version number: 0
Y: JanusGraph minor version number: 3 (0.3.x)/ 4 (0.4.x) etc
ZZ: JanusGraph patch version number in 2 digit version appended by 0 if needed. : 01/02/03 .. etc
AA: Library's Patch version numbers, starting with 00

Since PyPi normalizes the version numbers as normal numbers, we can trick it into thinking that the version we are following are valid numbers as follows:

X.Y.ZZAA then becomes X.Y.ZAA
Meaning, we don't append JanusGraph patch version number with additional 0. We just write the version number as it is. If a Path 10 is reached, then .ZAA becomes .ZZAA as follows:

JanusGraph version    Library Version, Patch 1
0.3.9                         0.3.901
0.3.10                       0.3.1001

If we think that we don't have fixed digits for version numbers, well we can think it in way that it is dynamic enough to accomodate our required use cases.

And, in addition to that I would like to propose a rule for Library Patch version numbers (AA) that it starts from 01 and not 00. This is to avoid following scenario:

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.1                          0.3.101                 0.3.101                              0.3.101
0.3.1                          0.3.100                 0.3.1                                  0.3.100

But I think of one drawback with this restricted approach is that, how do we tackle normalization when JanusGraph is on 1st release of a minor version. (0.3.0). In such scenario, following thing will happen with PyPi

JanusGraph version     Library Version      PyPi Normalized Version     NuGet version
0.3.0                          0.3.001                 0.3.1                                 0.3.001

We lose the information regarding which JanusGraph minor version that it.

Any ideas how do we proceed?


On Monday, 8 October 2018 21:28:37 UTC+5:30, Debasish Kanhar wrote:
Florian, Stephen. Thanks guys for your input. That was really a helpful comment but I was doing quick testing on what Version numbers are supported on PyPi (Where Python libs are hosted).

1. So, It got me wondering, because PyPi doesn't support uploading versions with tags in it. So something like "0.3.0101-beta1" will fail because it contains string which is Invalid.
2. Similarly, I thought will they support 4 digit versioning, and I tried "0.3.0.1" and it worked like a charm and the library got published to PyPi withoug any errors. Great news.
3. Then I tried out Florian's idea, having 3 digit codes, but 3rd one having 4 digits. Hence the analogous "0.3.0001" actually doesn;t get uploaded the way it is expected to. Python normalizes the version number, and hence 0.3.0001 now becomes 0.3.1. Similarly 0.3.0101 now becomes 0.3.101. Now due to this normalization, the Version numbers aren't getting reflected properly to PyPi. Looks like this is a technical drawback.

But looking at your comments, looks like NuGet doesn't support 4 digit SymVer versioning? If such is scenario, I don't know how do we reach a consensus here, as it looks like the version numbers supposed to be working with PyPi won't be working with NuGet or vice versa. 

On Sunday, 7 October 2018 17:22:53 UTC+5:30, Florian Hockmann wrote:

Thanks for your input on this, Stephen! This really got me thinking.


I think in the end it comes down to the question of what is more important for us to communicate to users with the version: Which version of JanusGraph (and therefore implicitly TinkerPop) is supported or whether new features or breaking changes are included in the library itself that are not related to an updated JanusGraph version?

The more I think about this, the more I tend towards primarily communicating the supported JanusGraph version. Once the libraries support all JanusGraph specific predicates and data types, there won’t be many changes to them. The only changes will probably be updated dependencies which is mostly the TinkerPop GLV and those versions will be in line with the TinkerPop version supported by JanusGraph. So, I guess the optimal solution for the library versions would include the supported JanusGraph version. That would also have the advantage that users won’t have to keep track of yet another version and ensure that everything is compatible (the compatibility matrix of JanusGraph is already complicated enough).


Unfortunately, we can’t completely copy the versioning strategy from Ogre as it uses 4 version elements and some package managers (like NuGet) expect SemVer style versions with only 3 elements. We could solve this by taking the JanusGraph version and then extending the third element with a version number for the library itself. So, something like this:


JanusGraph version   Library version
0.3.0                        0.3.0000
0.3.0                        0.3.0001
0.3.1                        0.3.0100
0.4.0                        0.4.0000

The first 2 digits of the third element reflect the third element of the JanusGraph version and the last 2 digits are for the library version. 2 digits are necessary in case JanusGraph reaches a version like 0.3.10 and the same for the library which could reach 0.3.0010.

The .NET Core SDK uses a similar versioning strategy. The only difference is that they only include the major and minor version of the .NET Core runtime as the patch version really only contains patches which is not the case for JanusGraph and TinkerPop. That allows them to include a minor and patch version together in a 3 digit third element of the version.

We could use this versioning when we agree that we only add breaking changes when a new JanusGraph version is out that allows breaking changes (next would be 0.4.0).

So, what do others say? Should we use versions like 0.3.0000?

Am Samstag, 6. Oktober 2018 17:41:18 UTC+2 schrieb Stephen Mallette:
I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-de...@googlegroups.com.
To post to this group, send email to jan...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [VOTE] JanusGraph 0.2.2 release

Florian Hockmann <f...@...>
 

+1

Am Dienstag, 9. Oktober 2018 23:09:57 UTC+2 schrieb Alexandr Porunov:

+1


Re: [VOTE] JanusGraph 0.2.2 release

Alexandr Porunov <alexand...@...>
 

+1


[VOTE] JanusGraph 0.2.2 release

Jason Plurad <plu...@...>
 

Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

Please note that the v0.2.2 tag has been updated. You can refresh your tags with this command:
        git tag -l | xargs git tag -d && git fetch -t

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 12, 2018 at 2:10 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad


Cleanup test suite

Jan....@...
 

Hi all,


During my work on Testcontainers (https://github.com/GDATASoftwareAG/janusgraph/tree/testcontainers), I needed to modified all tests files multiple times. These multiple changes can follows to mistakes in implementations. Besides, if something in the configuration has changed, you probably need to update all test classes.


Janusgraph test classes should become better manageable, for example, add new test classes, split up tests or detect difference between backend (completeness). 

I found two possible solution to improve:


1. Combine all tests into test suite, see PR https://github.com/JanusGraph/janusgraph/pull/1259 . My proof of concept based on solution from Tinkerpop with some changes for Janusgraph.

+ Reduced boilerplate, one provider file for one database backend and a suite file to define tests.

+ Improved ignoring of tests, currently tests are overwritten with an empty method. These method doesn't prevent to execute the startup and cleanup method for these ignored tests. (Performance improvement)

+ Changes of database configuration need to be done only once.

- Tests are only executable behind a test suite. (Can be probably fixed)

- It could only exists one provider per test project. (This need to be fixed)


2. Using Junit Rule for configuration.

+ Reduced boilerplate, one provider file for one database backend. 

+ Less code change (Smaller review).

+ Changes of database configuration need to be done only once.

-  All test classes need to be exists for all backends. (Current state) (An idea to write all of theses classes would be to auto generate these test classes.)


Besides, an upgrade to Junit 5 from Junit 4 can be a benefit in both cases, see https://junit.org/junit5/docs/current/user-guide/ .

I would appreciate any feedback to both present solution or do you have another possible solution? What should be the next steps to improve the current situation?

 

Greetings,

Jan


Re: [DISCUSS] Individual Versioning decision for GLV libraries

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

Florian, Stephen. Thanks guys for your input. That was really a helpful comment but I was doing quick testing on what Version numbers are supported on PyPi (Where Python libs are hosted).

1. So, It got me wondering, because PyPi doesn't support uploading versions with tags in it. So something like "0.3.0101-beta1" will fail because it contains string which is Invalid.
2. Similarly, I thought will they support 4 digit versioning, and I tried "0.3.0.1" and it worked like a charm and the library got published to PyPi withoug any errors. Great news.
3. Then I tried out Florian's idea, having 3 digit codes, but 3rd one having 4 digits. Hence the analogous "0.3.0001" actually doesn;t get uploaded the way it is expected to. Python normalizes the version number, and hence 0.3.0001 now becomes 0.3.1. Similarly 0.3.0101 now becomes 0.3.101. Now due to this normalization, the Version numbers aren't getting reflected properly to PyPi. Looks like this is a technical drawback.

But looking at your comments, looks like NuGet doesn't support 4 digit SymVer versioning? If such is scenario, I don't know how do we reach a consensus here, as it looks like the version numbers supposed to be working with PyPi won't be working with NuGet or vice versa. 

On Sunday, 7 October 2018 17:22:53 UTC+5:30, Florian Hockmann wrote:

Thanks for your input on this, Stephen! This really got me thinking.


I think in the end it comes down to the question of what is more important for us to communicate to users with the version: Which version of JanusGraph (and therefore implicitly TinkerPop) is supported or whether new features or breaking changes are included in the library itself that are not related to an updated JanusGraph version?

The more I think about this, the more I tend towards primarily communicating the supported JanusGraph version. Once the libraries support all JanusGraph specific predicates and data types, there won’t be many changes to them. The only changes will probably be updated dependencies which is mostly the TinkerPop GLV and those versions will be in line with the TinkerPop version supported by JanusGraph. So, I guess the optimal solution for the library versions would include the supported JanusGraph version. That would also have the advantage that users won’t have to keep track of yet another version and ensure that everything is compatible (the compatibility matrix of JanusGraph is already complicated enough).


Unfortunately, we can’t completely copy the versioning strategy from Ogre as it uses 4 version elements and some package managers (like NuGet) expect SemVer style versions with only 3 elements. We could solve this by taking the JanusGraph version and then extending the third element with a version number for the library itself. So, something like this:


JanusGraph version   Library version
0.3.0                        0.3.0000
0.3.0                        0.3.0001
0.3.1                        0.3.0100
0.4.0                        0.4.0000

The first 2 digits of the third element reflect the third element of the JanusGraph version and the last 2 digits are for the library version. 2 digits are necessary in case JanusGraph reaches a version like 0.3.10 and the same for the library which could reach 0.3.0010.

The .NET Core SDK uses a similar versioning strategy. The only difference is that they only include the major and minor version of the .NET Core runtime as the patch version really only contains patches which is not the case for JanusGraph and TinkerPop. That allows them to include a minor and patch version together in a 3 digit third element of the version.

We could use this versioning when we agree that we only add breaking changes when a new JanusGraph version is out that allows breaking changes (next would be 0.4.0).

So, what do others say? Should we use versions like 0.3.0000?

Am Samstag, 6. Oktober 2018 17:41:18 UTC+2 schrieb Stephen Mallette:
I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-de...@googlegroups.com.
To post to this group, send email to jan...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


[RESULT][VOTE] JanusGraph 0.3.1 release

Jason Plurad <plu...@...>
 

This vote is now closed with a total of 8 +1s, no +0s and no -1s. The results are:

BINDING VOTES:

+1  (3 -- Jason Plurad, Misha Brukman, Jerry He)
0   (0)
-1  (0)

NON-BINDING VOTES:

+1 (5 -- David Pitera, Alexandr Porunov, Florian Hockmann, Debasish Kanhar, Chris Hupman)
0  (0)
-1 (0)

Thank you very much,
Jason Plurad


Re: [DISCUSS] Individual Versioning decision for GLV libraries

Florian Hockmann <f...@...>
 

Thanks for your input on this, Stephen! This really got me thinking.


I think in the end it comes down to the question of what is more important for us to communicate to users with the version: Which version of JanusGraph (and therefore implicitly TinkerPop) is supported or whether new features or breaking changes are included in the library itself that are not related to an updated JanusGraph version?

The more I think about this, the more I tend towards primarily communicating the supported JanusGraph version. Once the libraries support all JanusGraph specific predicates and data types, there won’t be many changes to them. The only changes will probably be updated dependencies which is mostly the TinkerPop GLV and those versions will be in line with the TinkerPop version supported by JanusGraph. So, I guess the optimal solution for the library versions would include the supported JanusGraph version. That would also have the advantage that users won’t have to keep track of yet another version and ensure that everything is compatible (the compatibility matrix of JanusGraph is already complicated enough).


Unfortunately, we can’t completely copy the versioning strategy from Ogre as it uses 4 version elements and some package managers (like NuGet) expect SemVer style versions with only 3 elements. We could solve this by taking the JanusGraph version and then extending the third element with a version number for the library itself. So, something like this:


JanusGraph version   Library version
0.3.0                        0.3.0000
0.3.0                        0.3.0001
0.3.1                        0.3.0100
0.4.0                        0.4.0000

The first 2 digits of the third element reflect the third element of the JanusGraph version and the last 2 digits are for the library version. 2 digits are necessary in case JanusGraph reaches a version like 0.3.10 and the same for the library which could reach 0.3.0010.

The .NET Core SDK uses a similar versioning strategy. The only difference is that they only include the major and minor version of the .NET Core runtime as the patch version really only contains patches which is not the case for JanusGraph and TinkerPop. That allows them to include a minor and patch version together in a 3 digit third element of the version.

We could use this versioning when we agree that we only add breaking changes when a new JanusGraph version is out that allows breaking changes (next would be 0.4.0).

So, what do others say? Should we use versions like 0.3.0000?

Am Samstag, 6. Oktober 2018 17:41:18 UTC+2 schrieb Stephen Mallette:

I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-de...@googlegroups.com.
To post to this group, send email to janusgr...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


Re: [VOTE] JanusGraph 0.3.1 release

Jerry He <jerr...@...>
 

+1 

Downloaded the binary zip. Checked the signature.  Good.
Unzip it.  Looked at the directories and files.  Good.
Ran simple transactions and queries against HBase 1.2.6 and Solr 6.3.0.  Good.
Started gremlin-server and ran queries against the same backend configuration.  Good.
Started with a 0.2.1 graph, opened with JanusGraph 0.3.1 (with graph.allow-upgrade=true) and some simple tests.  Good.

Thanks,

Jerry

On Fri, Oct 5, 2018 at 9:11 AM, Chris Hupman <chris...@...> wrote:
+1


On Tuesday, October 2, 2018 at 6:48:31 PM UTC-7, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.3.1 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.3.1

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.3.1/janusgraph-0.3.1-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.3.1/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.3.1/janusgraph-0.3.1-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.3.1

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.3.1/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 5, 2018 at 10:00 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgraph-dev+unsubscribe@googlegroups.com.
To post to this group, send email to janusgraph-dev@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/6f689584-71ac-418d-af25-40262cb1a18f%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.


Re: [DISCUSS] Individual Versioning decision for GLV libraries

Stephen Mallette <spmal...@...>
 

I haven't been really following the discussion, so apologies if this has already been mentioned, but I've liked the approach that Ogre and gremlin-scala have taken with respect to TinkerPop - they just bind their releases to TinkerPop release numbers by adding a 4th number to the end. So for JanusGraph 0.4.0 you just have JanusGraph-Py 0.4.0.0. Then you can independently release JanusGraph-Py 0.4.0.1, 0.4.0.2 and so on. The advantage is that users will know exactly which versions work and are tested with which version of JanusGraph. Anyway....just something to consider.



On Sat, Oct 6, 2018 at 7:21 AM Florian Hockmann <f...@...> wrote:
How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/e8e0daa5-e0d0-48b1-9219-809c47fe5e33%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.


[CANCEL][VOTE] JanusGraph 0.2.2 release

Jason Plurad <plu...@...>
 

I opened up Issue 1285 for the storage incompatibility of upgrade from 0.2.1 to 0.2.2. I will start a new voting thread for 0.2.2 when the release with a fix is ready.

On Sat, Oct 6, 2018 at 1:16 AM Chris Hupman <chris...@...> wrote:
I ended up replacing that check with the concept of the graph.storage-version when I wrote the upgrade for 0.3.x. Either we can hard code 0.2.2 as allowed or we can back-port the upgrade functionality. 

It really comes down to how many more releases are we planning to have for 0.2.x.

I should be able to submit a fix for this Monday if no one else grabs it.

Chris 

On Fri, Oct 5, 2018 at 10:09 PM Jerry He <jerr...@...> wrote:
I was trying to do some testing:

JanusGraph 0.2.2 can not read graph from 0.2.1.

org.janusgraph.core.JanusGraphException: StorageBackend version is incompatible with current JanusGraph version: storage [0.2.1] vs. runtime [0.2.2]
        at org.janusgraph.graphdb.configuration.GraphDatabaseConfiguration.<init>(GraphDatabaseConfiguration.java:1434)

Jerry

On Fri, Oct 5, 2018 at 9:10 AM, Chris Hupman <chris...@...> wrote:
+1


On Tuesday, October 2, 2018 at 6:47:50 PM UTC-7, Jason Plurad wrote:
Hello,

We are happy to announce that JanusGraph 0.2.2 is ready for release.

The release artifacts can be found at this location:
        https://github.com/JanusGraph/janusgraph/releases/tag/v0.2.2

A binary distribution is provided for user convenience:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2.zip

The GPG key used to sign the release artifacts is available at:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/KEYS

The docs can be found here:
        https://github.com/JanusGraph/janusgraph/releases/download/v0.2.2/janusgraph-0.2.2-hadoop2-doc.zip
        (See also documentation preview site)

The release tag in Git can be found here:
        https://github.com/JanusGraph/janusgraph/tree/v0.2.2

The release notes are available here:
        https://github.com/JanusGraph/janusgraph/blob/v0.2.2/docs/changelog.adoc

This [VOTE] will open for the next 3 days --- closing Friday, October 5, 2018 at 10:00 PM EDT.
All are welcome to review and vote on the release, but only votes from TSC members are binding.
My vote is +1.


Thank you,
Jason Plurad

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/26dca088-213e-4d14-a429-4e2b7a5bf6ef%40googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to a topic in the Google Groups "JanusGraph developers" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/janusgraph-dev/VB1lImR9jRg/unsubscribe.
To unsubscribe from this group and all its topics, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/CAHkeaHUW3wifZFdB9%2BH2Zo34XfObpWd6OAv52jS3F%3D4d-oOUkg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "JanusGraph developers" group.
To unsubscribe from this group and stop receiving emails from it, send an email to janusgr...@....
To post to this group, send email to janusgr...@....
To view this discussion on the web visit https://groups.google.com/d/msgid/janusgraph-dev/CAL1T1LTVgZ3f1sAvv3BgSNN3cr%2B6i5O8N0uqD6Ae6a50ANs%3DFw%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.


Re: [DISCUSS] Individual Versioning decision for GLV libraries

Florian Hockmann <f...@...>
 

How do we bump minor and major versions?

If we agree on using SemVer, then that already tells us how to handle minor and major version. Taken from its summary:

  1. MINOR version when you add functionality in a backwards-compatible manner, and
  2. PATCH version when you make backwards-compatible bug fixes.
The only special case is that we can include breaking changes without having to bump to 1.0.0 as 1.0.0 reflects a certain stability of the API. So, I'd say that we wait until we actually have a breaking change and then decide whether it makes sense to bump to 1.0.0 or whether we simply want to bump the minor version and communicate the breaking change to users in the docs / release notes.

One thing that we haven't really discussed yet is how users know which version of JanusGraph is supported by which version of the library. My initial thoughts are that we include this information in the release notes when a newer JanusGraph version is supported and that we probably want to include a section in the docs of the libraries about version compatibility. Maybe it makes also sense to include this information also in the package metadata which is at least for .NET users the most prominent place for documentation.

Am Samstag, 6. Oktober 2018 09:36:06 UTC+2 schrieb Debasish Kanhar:
and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K

On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K


Re: [DISCUSS] Individual Versioning decision for GLV libraries

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

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us. : I agree with you, after going through your points, it seems that going forward with 0.y.z as version numbers is the right way to go forward.

Code breaking changes implies anything which might break user's code or even library. Just about anything. And well there will be minor such changes corresponding to few features being added. It would be better if we start with 0.y.z as version numbers.

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.: My bad. I just wanted to consider every scenario theoretically, and it doesn't seem like I was able to find a logical scenario where adding new feature breaks existing features. Maybe coz such scenario doesn't exist only ;-)

Anyways thanks Florian for getting a lot of points clear. I guess we now have concensous on following SymVer and starting with 0.y.z.

How do we bump minor and major versions? Would that follow my proposal which was a top of the thread?

Cheers
Debasish K


On Thursday, 4 October 2018 21:00:15 UTC+5:30, Florian Hockmann wrote:
Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

I just meant any breaking change which could also simply be that a new GraphSON version is used by default. It doesn't have to be a breaking code change in the library itself.

I didn't know that having major version 0 implies that API may change

That's simply part of SemVer (semantic versioning). It states:

Major version zero (0.y.z) is for initial development. Anything may change at any time. The public API should not be considered stable.

and users expect exactly that of a library that has a 0.y.z version. I think that makes sense for us.

Do you mean the end point API like the one used to connect to Server? Or few of syntax?

I mean anything that requires users to change their code. Your PR for example currently contains a JanusGraphClient that has a connect and a get_connection method. What if we want to use just one method that does both in the future? Or what if we decide to unify the APIs of the libraries for the different languages?
It's really hard to figure out a good API right from the start. So, it's good if we have the possibility to change the API in early versions without breaking users expectations. However, a version 1.y.z implies that the API is relatively stable.

Well isn't syntax probable to change if some conflicting or new feature comes in?

New features shouldn't require breaking changes usually. Adding something doesn't break existing code.

Am Donnerstag, 4. Oktober 2018 15:42:35 UTC+2 schrieb Debasish Kanhar:
Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature.: This sounds good, and better plan for going forward.

Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches: I'm still not able to imagine the scenario where such a code breaking change will be introduced. Code breaking changes for library I don't visualize yet, but code changes for user of library can be possible if few syntax or class changes in future.

as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance: This sounds like the way to go forward. Like for eg, in my upcoming release, I've changed the syntax of connecting to JanusGraph server. We can provide a upgrade notes, on what changes to code or user will be required, or else they can decide to stick to older version if they don't need the upgraded lib's features.

Then the only scenario I think where we might need to maintain 2 different versions will be either when JanusGraph's actively maintained versions contains more than 2 GraphSON versions (Like GSon 3 & 4) or when together 2 separate TinkerPop versions are supported (Though this later one might require less of maintenance)

I didn't know that having major version 0 implies that API may change. Do you mean the end point API like the one used to connect to Server? Or few of syntax? Well isn't syntax probable to change if some conflicting or new feature comes in? Like the way to connect to running instace of JanusGrpah server for example.


On Wednesday, 3 October 2018 16:44:12 UTC+5:30, Florian Hockmann wrote:
I also think that we should keep the number of maintained branches / versions as low as possible, ideally only 1 branch will be actively maintained. Adding new features (which requires a minor version bump) doesn't hinder users from upgrading in any way. So, I don't see why we would still maintain an older version without this new feature. Now, when a breaking change becomes necessary at some point in the future, we can still decide whether it's big enough to require maintaining 2 branches or whether it's so small that we can expect users to just upgrade to the new major version in which case we would only have to maintain that version.

But it seems as if we have reached consensus on using semantic versioning for the libraries. We just need to decide whether we want to start at version 1.0.0 or 0.0.1.
I would be ok with both versions, but I have a slight preference towards 0.0.1 as a major version of 0 implies that the API may change at any time which allows us to still make some general adjustments to the API.

Am Dienstag, 2. Oktober 2018 22:20:25 UTC+2 schrieb Jason Plurad:
> I'm still concerned about the number of releases which will need to be actively maintained as that keeps on increasing.

I would think as long as the drivers are largely backwards compatible, you'd be able to keep it to 2 active branches. Adding new features like schema management or geoshapes wouldn't break the previous functionality. And even if there were breaking changes, as long as you provide upgrade notes to notify users about syntax changes, they would be able to upgrade to the newer version or they can also choose to stick with the previous version despite being out of maintenance.


On Tuesday, October 2, 2018 at 2:20:36 PM UTC-4, Debasish Kanhar wrote:
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.

Cheers


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.

Cheers
Debasish K

741 - 760 of 1597