Versioning Extension

To be Reviewed By: 11/5/2021

Authors: Jacob Barrett Robert Houghton  

Status: Draft | Discussion | Development | Active | Dropped | Superseded

Superseded by: N/A

Related: N/A

Problem

When releasing a distribution of Geode or proving external extensions there is currently no extensible way to include version information in the version banners shown in gfsh and log files. To do so now requires core code modification to include additional version information.

Anti-Goals

This RFC does not aim to solve all extensibility within Geode nor will it cover all aspects of versioning. It is designed as stepping stone to better extensibility.

Solution

Two new internal service interfaces will be defined to retrieve information about the distribution of Geode and any distributed components. Implementations will be loaded using the ServiceLoader pattern. Both interfaces will implement 3 methods to provide basic version information that may be expanded over time.

@NotNull String getVersion() - Provides a string representation of the version. The format of this version is undefined but should not adorned with names or prefixes like "Geode" or "v". Some examples would be "1.15.0-build.123", "1.15.1", or "1.2-rc1".

@NotNull String getName() - Provides a string representation of the distribution or component name. The format of this string is undefined but should be short and meaningful when displayed alone and unadorned with version information. Some examples would be "Apache Geode" or "The Best IMDG".

@NotNull Map<@NotNull String, @NotNull String> getDetails() - Provides a map representation of all the version like information you might want to display in the full version or log preamble. The key and value formats are not defined. The basic version should be included in this output but the name should not.  For example:

{
  {"Version", "1.15.0"},
  {"Repository", "github.com/apache/geode"},
  {"Revision", "f5584205b0ee93904a5f2a9921459f99a1caa515"}
}

DistributionVersion

This interface is expected to have a single exported implementation within a given distribution of Geode. A default implementation, which is not exported as a service implementation, will report the Apache Geode open source distribution version information that we currently produce today. If an exported service implementation is found its version information will be displayed in place of the default's in all places where a singular distribution version and name are displayed. For example, this interface will control the display of gfsh version. This interface will not change the version information reported by any API or ABI, such as the REST interface version, binary protocol version, etc. If more than a single implementation is exported the first one loaded by ServiceLoader will be used, leading to indeterminate output.

Example output from gfsh:

$ gfsh version
2.4.1

$ gfsh
    _________________________     __
   / _____/ ______/ ______/ /____/ /
  / /  __/ /___  /_____  / _____  / 
 / /__/ / ____/  _____/ / /    / /  
/______/_/      /______/_/    /_/    2.4.1

Monitor and Manage The Best IMDG
gfsh>

ComponentVersion

This interface is used to provide aggregate version information about components of a distribution. A default, and exported implementation, will report the Apache Geode open source version information that we currently produce today. Any additional exported implementations will be reported as well. The order in which the components are reported is undefined. Examples of this output include gfsh version --full  and the log file preamble.

Example output from gfsh:

$ gfsh version --full
-----------------------------------------------------
Apache Geode
-----------------------------------------------------
Version: 1.15.0
Repository: github.com/apache/geode
Revision: f5584205b0ee93904a5f2a9921459f99a1caa515

-----------------------------------------------------
The Best IMDG
-----------------------------------------------------
Version: 2.4.1
Something-Important: 42

-----------------------------------------------------
Apache Spark for Geode
-----------------------------------------------------
Version: 1.2
Spark-Version: 3.2.0

Changes and Additions to Public Interfaces

For the near future these interfaces will remain internal.

Performance Impact

A minor impact should be expected for all commands the produce version information output. 

Backwards Compatibility and Upgrade Path

There should be no impact to API or ABI resulting in backwards compatibility issues.

Custom tooling that scrapes logs may need to be modified to work with the new gfsh version --full output. 

Prior Art

Previous distributions of Geode had recompiled and replaced the version properties file produced at build time. Doing so results in the loss of the Apache Geode version and branding information.

There is currently no way to enumeration component versions.

FAQ

N/A

Errata

N/A