[DISCUSS] Migration to some sane versioning methodology

[Mike Jumper <mi...@guac-dev.org>]

Hello all,

Guacamole has been in never-ending 0.9.x mode for a while, with a few huge
releases still receiving no more than a patch number bump. I think we
should look to migrating to a version numbering scheme which forces us to
assign numbers more rigorously based on compatibility and the nature of
changes made.

Currently, our answer to "what version of X should I use?" is to use the
latest version possible and not mix libraries/software from different
Guacamole releases. This is difficult to apply in practice, particularly
when the version of guacamole-common, guacamole-common-js, guacamole-ext,
etc. are not bumped due to not being modified in a particular release. The
only way to know which version should be used is to closely inspect the
applicable pom.xml.

I suggest, given a version MAJOR.MINOR.PATCH, we adopt the following strict
definitions of releases, starting with 1.0.0 for the next release:

1) A MAJOR release has removed or changed aspects of the existing public
interface (API, Guacamole protocol, etc.), and is thus incompatible as a
whole with any other MAJOR release. A MAJOR release MAY require third-party
software to make code changes or perform a rebuild to be compatible. All
Guacamole components MUST be bumped to match the new version, even if they
are unmodified, to explicitly denote their compatibility.

2) A MINOR release has added new aspects to the existing public interface
(API, Guacamole protocol, etc.). Components from previous MINOR or PATCH
releases remain compatible. A MINOR release MUST NOT require third-party
software leveraging the existing public interface (API, Guacamole protocol,
etc.) to make code changes or perform a rebuild to be compatible. Only
modified Guacamole components are bumped to match the new version.

3) A PATCH release MUST NOT touch the existing public interface (API,
Guacamole protocol, etc.) at all. Only modified Guacamole components are
bumped to match the new version.

For users, this would mean:

* Anything related to Guacamole version X is compatible only with Guacamole
version X.
* Extensions and guacd with version X.Y are compatible only with Guacamole
version X.Z where Z >= Y.
* Protocol plugins with version X.Y are compatible only with guacd version
X.Z where Z >= Y.
* guacd with version X.Y is compatible only with guacamole-common /
guacamole-common-js version X.Z where Z >= Y.
* Anything implementing the Guacamole protocol as defined in version X.Y is
compatible only with components from the X.Z release where Z >= Y.

Thoughts?

- Mike

Re: [DISCUSS] Migration to some sane versioning methodology

[Nick Couchman <vn...@apache.org>]

On Tue, Jan 23, 2018 at 3:35 PM, Mike Jumper <mi...@guac-dev.org>
wrote:

> Hello all,
>
> Guacamole has been in never-ending 0.9.x mode for a while, with a few huge
> releases still receiving no more than a patch number bump. I think we
> should look to migrating to a version numbering scheme which forces us to
> assign numbers more rigorously based on compatibility and the nature of
> changes made.
>
> Currently, our answer to "what version of X should I use?" is to use the
> latest version possible and not mix libraries/software from different
> Guacamole releases. This is difficult to apply in practice, particularly
> when the version of guacamole-common, guacamole-common-js, guacamole-ext,
> etc. are not bumped due to not being modified in a particular release. The
> only way to know which version should be used is to closely inspect the
> applicable pom.xml.
>
> I suggest, given a version MAJOR.MINOR.PATCH, we adopt the following strict
> definitions of releases, starting with 1.0.0 for the next release:
>
> 1) A MAJOR release has removed or changed aspects of the existing public
> interface (API, Guacamole protocol, etc.), and is thus incompatible as a
> whole with any other MAJOR release. A MAJOR release MAY require third-party
> software to make code changes or perform a rebuild to be compatible. All
> Guacamole components MUST be bumped to match the new version, even if they
> are unmodified, to explicitly denote their compatibility.
>
> 2) A MINOR release has added new aspects to the existing public interface
> (API, Guacamole protocol, etc.). Components from previous MINOR or PATCH
> releases remain compatible. A MINOR release MUST NOT require third-party
> software leveraging the existing public interface (API, Guacamole protocol,
> etc.) to make code changes or perform a rebuild to be compatible. Only
> modified Guacamole components are bumped to match the new version.
>
> 3) A PATCH release MUST NOT touch the existing public interface (API,
> Guacamole protocol, etc.) at all. Only modified Guacamole components are
> bumped to match the new version.
>
> For users, this would mean:
>
> * Anything related to Guacamole version X is compatible only with Guacamole
> version X.
> * Extensions and guacd with version X.Y are compatible only with Guacamole
> version X.Z where Z >= Y.
> * Protocol plugins with version X.Y are compatible only with guacd version
> X.Z where Z >= Y.
> * guacd with version X.Y is compatible only with guacamole-common /
> guacamole-common-js version X.Z where Z >= Y.
> * Anything implementing the Guacamole protocol as defined in version X.Y is
> compatible only with components from the X.Z release where Z >= Y.
>
> Thoughts?
>
> - Mike
>

I'd definitely support this type of change in versioning moving forward,
and the changes you've suggested make perfect sense to me.  Clearly you've
thought this one out quite a bit.

I'd also offer a suggestion of using version numbering changes as a gateway
for the following:
- More frequent releases, particularly of the patch variety.  I'm not
suggesting that every commit or even JIRA issue constitute a release, but
it at least allows us to determine if certain fixes are not going to cause
compatibility issues and cluster a few together into either a patch or
minor release.  Obviously this needs to be balanced with adequate time for
testing, but simple bug fixes should be reasonably quick to verify and
release in this type of category with less testing required than major
things like additional database support, authentication modules, display
protocols, etc.
- A better-defined road-map, where the community can see (and provide input
into) where we're going with certain releases.  I'm not suggesting a rigid
approach and definitely don't want to do this at the cost of flexibility -
I think we should maintain a lot of the flexibility that has defined the
project thus far - but it gives us an opportunity, maybe for the major
releases more than anything, to say that, for example, release 1.0 will
target adding RADIUS support and a X.org driver, release 2.0 will target
compatibility for FreeRDP 2.0, etc., subject to change at the whim of the
development community :-).  (Just examples, not trying to lobby for
anything at this point.)

Again, these are just suggestions that are somewhat-related to this
discussion.

-Nick

Re: [DISCUSS] Migration to some sane versioning methodology

[Mike Jumper <mi...@guac-dev.org>]

On Tue, Jan 23, 2018 at 1:30 PM, Greg Trasuk <tr...@stratuscom.com> wrote:

> Makes sense to me.  You might also want to consider any changes to the
> formats of configuration files as part of the version scheme.  e.g, it
> would be nice to think that a MINOR version change could be dropped in to
> an existing server without changes to configs (or setup scripts) apart from
> the new ‘war’ file.
>

Agreed.

- Mike

Re: [DISCUSS] Migration to some sane versioning methodology

[Greg Trasuk <tr...@stratuscom.com>]

Makes sense to me.  You might also want to consider any changes to the formats of configuration files as part of the version scheme.  e.g, it would be nice to think that a MINOR version change could be dropped in to an existing server without changes to configs (or setup scripts) apart from the new ‘war’ file.

Cheers,

Greg Trasuk

> On Jan 23, 2018, at 3:35 PM, Mike Jumper <mi...@guac-dev.org> wrote:
> 
> Hello all,
> 
> Guacamole has been in never-ending 0.9.x mode for a while, with a few huge
> releases still receiving no more than a patch number bump. I think we
> should look to migrating to a version numbering scheme which forces us to
> assign numbers more rigorously based on compatibility and the nature of
> changes made.
> 
> Currently, our answer to "what version of X should I use?" is to use the
> latest version possible and not mix libraries/software from different
> Guacamole releases. This is difficult to apply in practice, particularly
> when the version of guacamole-common, guacamole-common-js, guacamole-ext,
> etc. are not bumped due to not being modified in a particular release. The
> only way to know which version should be used is to closely inspect the
> applicable pom.xml.
> 
> I suggest, given a version MAJOR.MINOR.PATCH, we adopt the following strict
> definitions of releases, starting with 1.0.0 for the next release:
> 
> 1) A MAJOR release has removed or changed aspects of the existing public
> interface (API, Guacamole protocol, etc.), and is thus incompatible as a
> whole with any other MAJOR release. A MAJOR release MAY require third-party
> software to make code changes or perform a rebuild to be compatible. All
> Guacamole components MUST be bumped to match the new version, even if they
> are unmodified, to explicitly denote their compatibility.
> 
> 2) A MINOR release has added new aspects to the existing public interface
> (API, Guacamole protocol, etc.). Components from previous MINOR or PATCH
> releases remain compatible. A MINOR release MUST NOT require third-party
> software leveraging the existing public interface (API, Guacamole protocol,
> etc.) to make code changes or perform a rebuild to be compatible. Only
> modified Guacamole components are bumped to match the new version.
> 
> 3) A PATCH release MUST NOT touch the existing public interface (API,
> Guacamole protocol, etc.) at all. Only modified Guacamole components are
> bumped to match the new version.
> 
> For users, this would mean:
> 
> * Anything related to Guacamole version X is compatible only with Guacamole
> version X.
> * Extensions and guacd with version X.Y are compatible only with Guacamole
> version X.Z where Z >= Y.
> * Protocol plugins with version X.Y are compatible only with guacd version
> X.Z where Z >= Y.
> * guacd with version X.Y is compatible only with guacamole-common /
> guacamole-common-js version X.Z where Z >= Y.
> * Anything implementing the Guacamole protocol as defined in version X.Y is
> compatible only with components from the X.Z release where Z >= Y.
> 
> Thoughts?
> 
> - Mike