opensearch-project / opensearch-project/OpenSearch

[Version] Rebase versioning to 1.0.0 with bwc support

Open
#417 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

discuss help wanted Meta Re-version
Dominant language
Java
Stars
13.7k
Forks
3k
Avg merge
2d 23h
Merged PRs (30d)
108

Description

This issue documents the rebase of the versioning from the forked predecessor version 7.10.2* to OpenSearch 1.0.0.

Existing Version Implementation

Versioning is essentially implemented as a class wrapper around a version id integer that provides a semantic API for relating between versions. The logic for the version id integer is XXYYZZAA where:

* XX is major version
* YY is minor version
* ZZ is revision / bugfix
* AA is alpha/beta/RC/GA builds  (values < 25 are alpha, 25 >= and < 50 are beta, 50 >= and <99 are RC, and 99 is GA)

This semantically enables before & after checks on the version id integers. Following this contract the maximum possible version number is 99.99.99.99 (or 99999999 in integer space).

Rebased OpenSearch Version Change

To keep backwards compatibility with the predecessor (e.g., 7.10 of the predecessor is treated as an earlier version of OpenSearch 1.0), the following must hold true:

* OpenSearch versionid integer space must be higher than the predecessors integer space. 
* Future releases of the predecessor must remain separated and easily identifiable from future releases of OpenSearch

The initial approach is as follows:

  1. split the existing Version class into two:
    a. new LegacyESVersion class for holding 6.x and 7.x version ids and semantics
    b. existing Version for holding the rebased OpenSearch version 1.x version ids and semantics (e.g., OpenSearch 1.0.0.alpha1 == Version.V_1_0_0_alpha1).
  2. allocate a new integer space for OpenSearch versioning
    a. Legacy versionid space is a maximum of 99999999; mapping to 27 bits
    b. OpenSearchID space will use the 28th bit as an identifier; when flipped to 1 the versionid is recognized as an OpenSearch version id.
    c. The remaining version id logic of the predecessor is retained for versions of OpenSearch (e.g., XX.YY.ZZ.AA). This keeps all of the semantics throughout the code base unchanged.
  3. LegacyESVersion is used in all existing version check locations. (e.g., LegacyESVersion.V_7_10_0)
  4. Breaking changes or new features that are not backward compatible will use the existing Version class like before (but this will now represent OpenSearch versions going forward)
Examples
  1. The following code executes for indexes created on or later than Predecessor version 6.6.0
 if (indexCreatedVersion.onOrAfter(LegacyESVersion.V_6_6_0) {
    // do some stuff
 }
  1. The following code executes for transport data received by a client deployed before the OpenSearch 1.0.0 alpha 1 release (forward compatibility)
 if (streamInput.getVersion().onOrBefore(Version.V_1_0_0_alpha1)) {
    // do some stuff for a legacy client
 } else {
    // do some new cool stuff
 }
Notes

logs
./gradlew bwcTest

Task :distribution:bwc:bugfix:checkoutBwcBranch FAILED
Performing checkout of opensearch-project/7.10...
Exec output and error:
| Output for git:error: pathspec 'opensearch-project/7.10' did not match any file(s) known to git

Task :server:compileJava
Note: Some input files use or override a deprecated API.
Note: Recompile with -Xlint:deprecation for details.
Note: Some input files use unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

FAILURE: Build failed with an exception.

  • What went wrong:
    Execution failed for task ':distribution:bwc:bugfix:checkoutBwcBranch'.

Process 'command 'git'' finished with non-zero exit value 1

Subtasks

  • :distribution:bwc:bugfix:checkoutBwcBranch FAILED
  • This approach is implemented on a feature branch and will be merged to main either for, or initially following, the initial opening of the repositories, and this issue will remain open as a discuss issue for anyone that wants to improve or propose a new or complete change of the design. (encouraged)
  • On day 1 of the opening of the repository Initial integration and unit tests may or may not be completely finished.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing Version implementation and the proposed LegacyESVersion split described in the issue, then run ./gradlew bwcTest to reproduce the checkoutBwcBranch failure. Confirm the version-id separation, compatibility checks, and BWC behavior before treating the work as complete; the issue notes that the approach is on a feature branch and remains open for design discussion.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
backend, build-system
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.