From 98aac97d4cf07c8133d20e76e26b53658906c6d2 Mon Sep 17 00:00:00 2001 From: Martin Gaievski Date: Tue, 29 Mar 2022 17:18:07 -0700 Subject: [PATCH] Adding documentation on codec versioning (#337) Signed-off-by: Martin Gaievski --- DEVELOPER_GUIDE.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/DEVELOPER_GUIDE.md b/DEVELOPER_GUIDE.md index d7ed6d8d4a..18213fa9de 100644 --- a/DEVELOPER_GUIDE.md +++ b/DEVELOPER_GUIDE.md @@ -14,6 +14,7 @@ - [Debugging](#debugging) - [Backwards Compatibility Testing](#backwards-compatibility-testing) - [Adding new tests](#adding-new-tests) + - [Codec Versioning](#codec-versioning) - [Submitting Changes](#submitting-changes) # Developer Guide @@ -265,6 +266,26 @@ Here, we are testing BWC Tests with BWC version of plugin as 1.0.0.0. Make sure Before adding any new tests to Backward Compatibility Tests, we should be aware that the tests in BWC are not independent. While creating an index, a test cannot use the same index name if it is already used in other tests. Also, adding extra operations to the existing test may impact other existing tests like graphCount. +## Codec Versioning + +Starting from 2.0 release the new versioning for codec has been introduced. Two positions will be used to define the version, +in format 'X.Y', where 'X' corresponds to underlying version of Lucene and 'Y' is the version of the format. + +Codec version is used in following classes and methods: +- org.opensearch.knn.index.codec.KNNXYCodec.KNNXYCodec +- org.opensearch.knn.index.codec.KNNFormatFactory.createKNNXYFormat + +These classes and methods are tied directly to Lucene version represented by 'X' part. +Other classes use the delegate pattern so no direct tie to Lucene version are related to format and represented by 'Y' + +- BinaryDocValues +- CompoundFormat +- DocValuesConsumer +- DocValuesReader + +Version '910' is going to be the first such new version. It corresponds to Lucene 9.1 that is used by the underlying OpenSearch 2.0 and initial +version of the format classes. If in future we need to adjust something in format logic, we only increment the 'Y' part and version became '911'. + ## Submitting Changes See [CONTRIBUTING](CONTRIBUTING.md).