Now that we have repos ready for a Python and a .NET library that extend the TinkerPop GLVs for JanusGraph, we need to decide on how those libraries should be released and how we want to handle versioning for them. I see basically two different options that we should discuss:

1. Option: The libraries use the same versions as JanusGraph itself, e.g., right now they would use 0.3.0 and maybe additionally a 0.2.1 version.

This approach has mainly the advantage that it's very clear for users which version of a library is compatible with which version of JanusGraph. E.g., a user of JanusGraph 0.2.1 could use JanusGraph.Net with version 0.2.1 and wouldn't have to deal with incompatibilities between GraphSON versions for example. However, from my experience with Gremlin.Net, most users will simply always use the highest version available, even if their database only supports an older TinkerPop version. (This behaviour can be seen in the NuGet download statistics for Gremlin.Net which always show a much higher number of downloads for the 3.3.z versions compared to the 3.2.z versions.)

The big disadvantage for this approach is of course that the libraries can only release new versions when JanusGraph releases a new version. So, bug fixes and new features always have to wait for the next release of JanusGraph, although they are not really related to each other. We would therefore slow down the development of the libraries only to have consistent version numbers.

2. Option: Each library could use its own versions, independent of the other libraries and the main JanusGraph project.

This would of course enable the libraries to release bug fixes or new features at their own pace, independent of the main project.

One disadvantage would be that we would have to convey the version compatibility in the docs as it wouldn't be apparent just from the version number of the library itself.

Another disadvantage I see here is how we would handle documentation for those libraries: I assume that we want to document the libraries also in docs.janusgraph.org but that is currently released together with JanusGraph itself. Therefore, documentation of a new feature in a library would only be available after the next JanusGraph release or we need to find a way to release the docs also independently of JanusGraph. Any thoughts on that?

I'm personally leaning towards the second option with independent version numbers to enable an independent release frequency for the libraries.

Other opinions or thoughts on this topic?

I'd prefer the second option. It'll be difficult to keep version numbers aligned at all times across projects without restricting the velocity of each repo.

The main thing to ensure is that the GLV documentation has an updated version compatibility matrix at all times, which version of the GLV is compatible with which version of JanusGraph. I noticed during the config of the repo that we could enable gh-pages for it, so unrelated to the main thread, where to host the driver docs (gh-pages, docs.janusgraph.org, other ideas) is something to think about.


On Wednesday, August 15, 2018 at 8:08:21 AM UTC-4, Florian Hockmann wrote:

Now that we have repos ready for a Python and a .NET library that extend the TinkerPop GLVs for JanusGraph, we need to decide on how those libraries should be released and how we want to handle versioning for them. I see basically two different options that we should discuss:

1. Option: The libraries use the same versions as JanusGraph itself, e.g., right now they would use 0.3.0 and maybe additionally a 0.2.1 version.

This approach has mainly the advantage that it's very clear for users which version of a library is compatible with which version of JanusGraph. E.g., a user of JanusGraph 0.2.1 could use JanusGraph.Net with version 0.2.1 and wouldn't have to deal with incompatibilities between GraphSON versions for example. However, from my experience with Gremlin.Net, most users will simply always use the highest version available, even if their database only supports an older TinkerPop version. (This behaviour can be seen in the NuGet download statistics for Gremlin.Net which always show a much higher number of downloads for the 3.3.z versions compared to the 3.2.z versions.)

The big disadvantage for this approach is of course that the libraries can only release new versions when JanusGraph releases a new version. So, bug fixes and new features always have to wait for the next release of JanusGraph, although they are not really related to each other. We would therefore slow down the development of the libraries only to have consistent version numbers.

2. Option: Each library could use its own versions, independent of the other libraries and the main JanusGraph project.

This would of course enable the libraries to release bug fixes or new features at their own pace, independent of the main project.

One disadvantage would be that we would have to convey the version compatibility in the docs as it wouldn't be apparent just from the version number of the library itself.

Another disadvantage I see here is how we would handle documentation for those libraries: I assume that we want to document the libraries also in docs.janusgraph.org but that is currently released together with JanusGraph itself. Therefore, documentation of a new feature in a library would only be available after the next JanusGraph release or we need to find a way to release the docs also independently of JanusGraph. Any thoughts on that?

I'm personally leaning towards the second option with independent version numbers to enable an independent release frequency for the libraries.

Other opinions or thoughts on this topic?

The problem I see with 4 digit versions where the first 3 are given by the JanusGraph version is that we couldn't express whether a release is a patch release or whether it contains new features (or even breaking changes).

so unrelated to the main thread, where to host the driver docs (gh-pages, docs.janusgraph.org, other ideas) is something to think about.

That is definitely an important point. If we decide for option 1 to bind the GLV library releases to JG releases, then we could of course just use docs.janusgraph.org as then everything will be deployed together. However, when the libraries are released independently of JG, then we would need a more flexible approach to release the docs. Would it be possible to introduce new doc areas like docs.janusgraph.org/dotnet/0.1.0/getting-started.html? Otherwise I'd say that we need another place for the library docs and the gh-pages or maybe readthedocs.org could be a good solution.

Am Donnerstag, 16. August 2018 12:03:56 UTC+2 schrieb Debasish Kanhar:

I would prefer any version, but I was thinking maybe aligning with JanusGraph version shall make it better, as user won't have to have a headache to which version to download, and it also gives us flexibility of not maintaining compartibility matrix for GLV version vs JanusGraph version.

But as mentioned by Florian and Jason, the issue with that approach will be that we can't target minor fixes, thus reducing the velocity of repo.

To overcome that, I would suggest a 4 digit version number like x.y.z.A, where A would be minor version corresponding to the GLV repo.

Let's say, I develop JanusGraph python drivers for JG 0.2.1, then my first version of GLV would be 0.2.1.0, followed by 0.2.1.1 and so on. That keeps us in sync with JanusGraph version, thus reducing headache for maintining compatibility matrix, and also gives us flexibility with minor fixes required for that driver.

What would everyone say with this proposal, a 4 digit versions?

On Wednesday, 15 August 2018 19:15:49 UTC+5:30, Jason Plurad wrote:

I'd prefer the second option. It'll be difficult to keep version numbers aligned at all times across projects without restricting the velocity of each repo.

The main thing to ensure is that the GLV documentation has an updated version compatibility matrix at all times, which version of the GLV is compatible with which version of JanusGraph. I noticed during the config of the repo that we could enable gh-pages for it, so unrelated to the main thread, where to host the driver docs (gh-pages, docs.janusgraph.org, other ideas) is something to think about.


On Wednesday, August 15, 2018 at 8:08:21 AM UTC-4, Florian Hockmann wrote:

Now that we have repos ready for a Python and a .NET library that extend the TinkerPop GLVs for JanusGraph, we need to decide on how those libraries should be released and how we want to handle versioning for them. I see basically two different options that we should discuss:

1. Option: The libraries use the same versions as JanusGraph itself, e.g., right now they would use 0.3.0 and maybe additionally a 0.2.1 version.

This approach has mainly the advantage that it's very clear for users which version of a library is compatible with which version of JanusGraph. E.g., a user of JanusGraph 0.2.1 could use JanusGraph.Net with version 0.2.1 and wouldn't have to deal with incompatibilities between GraphSON versions for example. However, from my experience with Gremlin.Net, most users will simply always use the highest version available, even if their database only supports an older TinkerPop version. (This behaviour can be seen in the NuGet download statistics for Gremlin.Net which always show a much higher number of downloads for the 3.3.z versions compared to the 3.2.z versions.)

The big disadvantage for this approach is of course that the libraries can only release new versions when JanusGraph releases a new version. So, bug fixes and new features always have to wait for the next release of JanusGraph, although they are not really related to each other. We would therefore slow down the development of the libraries only to have consistent version numbers.

2. Option: Each library could use its own versions, independent of the other libraries and the main JanusGraph project.

This would of course enable the libraries to release bug fixes or new features at their own pace, independent of the main project.

One disadvantage would be that we would have to convey the version compatibility in the docs as it wouldn't be apparent just from the version number of the library itself.

Another disadvantage I see here is how we would handle documentation for those libraries: I assume that we want to document the libraries also in docs.janusgraph.org but that is currently released together with JanusGraph itself. Therefore, documentation of a new feature in a library would only be available after the next JanusGraph release or we need to find a way to release the docs also independently of JanusGraph. Any thoughts on that?

I'm personally leaning towards the second option with independent version numbers to enable an independent release frequency for the libraries.

Other opinions or thoughts on this topic?

Yes, we can publish driver docs easily under docs.janusgraph.org/dotnet/x.y.z/index.html

I still think version numbers should be independent between projects. We already have a dizzying array of dependencies, and trying to align them would be futile.

On Thursday, August 16, 2018 at 7:58:36 AM UTC-4, Florian Hockmann wrote:

The problem I see with 4 digit versions where the first 3 are given by the JanusGraph version is that we couldn't express whether a release is a patch release or whether it contains new features (or even breaking changes).

so unrelated to the main thread, where to host the driver docs (gh-pages, docs.janusgraph.org, other ideas) is something to think about.

That is definitely an important point. If we decide for option 1 to bind the GLV library releases to JG releases, then we could of course just use docs.janusgraph.org as then everything will be deployed together. However, when the libraries are released independently of JG, then we would need a more flexible approach to release the docs. Would it be possible to introduce new doc areas like docs.janusgraph.org/dotnet/0.1.0/getting-started.html? Otherwise I'd say that we need another place for the library docs and the gh-pages or maybe readthedocs.org could be a good solution.

Am Donnerstag, 16. August 2018 12:03:56 UTC+2 schrieb Debasish Kanhar:

I would prefer any version, but I was thinking maybe aligning with JanusGraph version shall make it better, as user won't have to have a headache to which version to download, and it also gives us flexibility of not maintaining compartibility matrix for GLV version vs JanusGraph version.

But as mentioned by Florian and Jason, the issue with that approach will be that we can't target minor fixes, thus reducing the velocity of repo.

To overcome that, I would suggest a 4 digit version number like x.y.z.A, where A would be minor version corresponding to the GLV repo.

Let's say, I develop JanusGraph python drivers for JG 0.2.1, then my first version of GLV would be 0.2.1.0, followed by 0.2.1.1 and so on. That keeps us in sync with JanusGraph version, thus reducing headache for maintining compatibility matrix, and also gives us flexibility with minor fixes required for that driver.

What would everyone say with this proposal, a 4 digit versions?

On Wednesday, 15 August 2018 19:15:49 UTC+5:30, Jason Plurad wrote:

I'd prefer the second option. It'll be difficult to keep version numbers aligned at all times across projects without restricting the velocity of each repo.

The main thing to ensure is that the GLV documentation has an updated version compatibility matrix at all times, which version of the GLV is compatible with which version of JanusGraph. I noticed during the config of the repo that we could enable gh-pages for it, so unrelated to the main thread, where to host the driver docs (gh-pages, docs.janusgraph.org, other ideas) is something to think about.


On Wednesday, August 15, 2018 at 8:08:21 AM UTC-4, Florian Hockmann wrote:

Now that we have repos ready for a Python and a .NET library that extend the TinkerPop GLVs for JanusGraph, we need to decide on how those libraries should be released and how we want to handle versioning for them. I see basically two different options that we should discuss:

1. Option: The libraries use the same versions as JanusGraph itself, e.g., right now they would use 0.3.0 and maybe additionally a 0.2.1 version.

This approach has mainly the advantage that it's very clear for users which version of a library is compatible with which version of JanusGraph. E.g., a user of JanusGraph 0.2.1 could use JanusGraph.Net with version 0.2.1 and wouldn't have to deal with incompatibilities between GraphSON versions for example. However, from my experience with Gremlin.Net, most users will simply always use the highest version available, even if their database only supports an older TinkerPop version. (This behaviour can be seen in the NuGet download statistics for Gremlin.Net which always show a much higher number of downloads for the 3.3.z versions compared to the 3.2.z versions.)

The big disadvantage for this approach is of course that the libraries can only release new versions when JanusGraph releases a new version. So, bug fixes and new features always have to wait for the next release of JanusGraph, although they are not really related to each other. We would therefore slow down the development of the libraries only to have consistent version numbers.

2. Option: Each library could use its own versions, independent of the other libraries and the main JanusGraph project.

This would of course enable the libraries to release bug fixes or new features at their own pace, independent of the main project.

One disadvantage would be that we would have to convey the version compatibility in the docs as it wouldn't be apparent just from the version number of the library itself.

Another disadvantage I see here is how we would handle documentation for those libraries: I assume that we want to document the libraries also in docs.janusgraph.org but that is currently released together with JanusGraph itself. Therefore, documentation of a new feature in a library would only be available after the next JanusGraph release or we need to find a way to release the docs also independently of JanusGraph. Any thoughts on that?

I'm personally leaning towards the second option with independent version numbers to enable an independent release frequency for the libraries.

Other opinions or thoughts on this topic?