[tinkerpop] branch master updated: Updated release/versioning docs with PATCH

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/master by this push:
     new 5e2f0ae  Updated release/versioning docs with PATCH
     new 89ea5ae  Merge branch '3.5-dev'
5e2f0ae is described below

commit 5e2f0aeea9b898cc6382e65e838f1eaa14c34541
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Mon Nov 1 14:46:47 2021 -0400

    Updated release/versioning docs with PATCH
    
    https://lists.apache.org/thread/qrm34od9rv1j9026yzkk19or21fhzllo CTR
---
 docs/src/dev/developer/contributing.asciidoc   | 58 ++++++++++++--------------
 docs/src/dev/developer/for-committers.asciidoc | 12 +++++-
 2 files changed, 36 insertions(+), 34 deletions(-)

diff --git a/docs/src/dev/developer/contributing.asciidoc b/docs/src/dev/developer/contributing.asciidoc
index 1d4dea9..ce626bc 100644
--- a/docs/src/dev/developer/contributing.asciidoc
+++ b/docs/src/dev/developer/contributing.asciidoc
@@ -237,40 +237,34 @@ the changes brings extensive conflict between branches.
 
 On successful review, the *pull request will be merged* to the main repository and the JIRA issue will be closed.
 
+[[versioning]]
 == Versioning
 
-TinkerPop version numbers follow a format of `MAJOR.MINOR.PATCH`, where:
-
-* `MAJOR` version is incremented for epochs of thinking around TinkerPop and its relation to the graph ecosystem.
-* `MINOR` version is incremented when incompatible changes cannot be avoided.
-* `PATCH` version is incremented when changes are backward compatible.
-
-The number for `MAJOR` rarely changes and when it does, it typically represents a complete re-write of the software
-and thus massive changes can be expected. As a result of the definition for `MAJOR`, we tend to focus on the other
-two numbers when considering where changes will land.
-
-The driving question for determining if a change is suitable for `MINOR` or `PATCH` versions is whether or not the
-change introduces some form of incompatibility. As the focus for making the determination is "breaking change", we
-therefore allow the option for new features to land in `PATCH` versions. Taking this approach, lengthens the life span
-of `MINOR` versions considerably which is helpful to graph providers looking for stable long-lived support for a
-particular release line.
-
-With all of the above rules in mind, there are some subtle considerations when trying to determine where a change
-should land:
-
-* A `PATCH` may take a breaking change if that breaking change:
-** Is necessary to fix a critical bug.
-** Has a highly limited breaking scope (e.g. a utility class that no one would likely use)
-* It is preferred that new features go to `MINOR`, but it is sometimes the case that they will make their way
-to `PATCH` if the features are being added to a language variant to bring it in line with features already in core.
-* The preference is to upgrade dependencies in `MINOR` rather than in `PATCH` though exceptions can be made as in the
-case of a CVE.
-* The preference is to find deprecation paths whenever possible.
-
-Ultimately, the goal is to be able to make it so that any `PATCH` will work with any version of that line on the
-server. In doing so, it is acceptable for the language variants to lag behind core features within a `MINOR` version,
-though we should be diligent in catching up all lagged features within patches before we stop a patch cycle. In other
-words, we should only be content to stop support on a `MINOR` line once all the languages hold the same functionality.
+TinkerPop version numbers follow a format of `EPOCH.MAJOR.MINOR.PATCH`, where:
+
+* `EPOCH` version is incremented for epochs of thinking around TinkerPop and its relation to the graph ecosystem and is part of a complete release.
+* `MAJOR` version is incremented for incompatible changes and is part of a complete release.
+* `MINOR` version is incremented for backward compatible changes and is part of a complete release.
+* `PATCH` version is incremented for backward compatible bug fixes and typically only applied to client modules for partial release.
+
+The above definitions refer to notions of "complete" and "partial" releases. A complete release is one that releases
+all TinkerPop components across all languages. A partial release is one that releases just a single module of a
+driver/client. A partial release is helpful in that it decouples the release of client/driver modules from what are
+typically server modules. In this way, for example, a small fix can be applied and released around .NET without having
+to release all the other components which may not have experienced any real change.
+
+The number for `EPOCH` rarely changes and when it does, it typically represents a complete re-write of the software
+and thus massive changes can be expected. As a result of the definition for `EPOCH`, there is greater focus on the other
+three numbers when considering where changes will land:
+
+1. A client with a specific `EPOCH.MAJOR.MINOR` will be backward compatible with user application code written for
+`EPOCH.MAJOR.MINOR`.
+1. A client with specific `EPOCH.MAJOR` will be backward compatible with the `EPOCH.MAJOR` version of the server.
+
+A complete release is always just `EPOCH.MAJOR.MINOR` where the `PATCH` is inferred as "0", thus 3.6.x line would
+initially release all components as `3.6.0`. A `PATCH` number must start with "1" within a release because of how
+link:https://github.com/NuGet/Home/issues/7376[Nuget treats "0"]. If it was determined that `gremlin-python` needed a
+special release then it could be released independently of the other modules as `3.6.0.1`.
 
 In short, the dev mailing list is open to discussion on where a change will land. The discussion just needs to have
 good reasoning and use the general principles above as a framework for coming to a consensus.
diff --git a/docs/src/dev/developer/for-committers.asciidoc b/docs/src/dev/developer/for-committers.asciidoc
index 01a4713..7270daa 100644
--- a/docs/src/dev/developer/for-committers.asciidoc
+++ b/docs/src/dev/developer/for-committers.asciidoc
@@ -116,6 +116,10 @@ Changes to earlier branches should merge forward toward `master` (e.g. `3.5-dev`
 more about this process in the <<pull-requests, Pull Requests>> section. Note that `4.0-dev` is rebased on `master`
 and currently behaves as a fresh repository as all 3.x content was removed.
 
+As described in <<versioning,versioning>>, it is possible to do a "partial" release which will utilize a four-digit
+version that starts with a "1" (e.g. `3.6.0.1`). The branching strategy for a partial release requires that a `-dev`
+branch be created with the three digit prefix.
+
 Other branches may be created for collaborating on features or for RFC's that other developers may want to inspect.
 It is suggested that the JIRA issue ID be used as the prefix, since that triggers certain automation, and it provides a
 way to account for the branch lifecycle, i.e. "Who's branch is this, and can I delete it?"
@@ -127,8 +131,12 @@ Developers should remove their own branches when they are no longer needed.
 
 == Tags
 
-Tags are used for milestones, release candidates, and approved releases.  Please refrain from creating arbitrary
-tags, as they produce permanent clutter.
+Tags are used for milestones, release candidates, and approved <<versioning,partial and complete releases>>. Tags for a
+complete release are simply defined by the three-digit version number. Tags for a partial release, should be prefixed
+by the individual language relevant to that release. For example, if there is an initial partial release for `3.6.0`
+on `gremlin-python` then the tag should be `3.6.0.1-python`.
+
+Please refrain from creating arbitrary tags, as they produce permanent clutter.
 
 == Issue Tracker Conventions