Feature: SDK versioning document

[6r1d]

Let's discuss @dmitrivenger's SDK versioning document.

P.S.: the document number should be updated.

[0x009922]

Suggested change

	- `MAJOR`: Incremented only when there are breaking changes in the SDK itself, regardless of Iroha Core's version.
	- `MAJOR`: Incremented only when there are breaking API changes in the SDK itself, regardless of Iroha Core's version.

[Mingela]

Though there is no sense to try keeping existing SDK API if Iroha API changes, i.e. encode the entire signature and parameters in an abstract way or create another level of abstraction on the SDK level exclusively. So I'd rather add something like this.

Suggested change

	- `MAJOR`: Incremented only when there are breaking changes in the SDK itself, regardless of Iroha Core's version.
	- `MAJOR`: Incremented only when there are breaking API changes in the SDK itself, implied either from Iroha API change or SDK's 'internal' roadmap implementation.

Another point is that we probably should to maintain more or less the same API in the SDK the Iroha offers so it's not clear what kind of API changes may be expected just on the SDK level. But I agree to cover that as a possibility.

[0x009922]

I think we are not the same page about what we mean by "API".

I use term API (Application Programming Interface) in a broad sense. SDK's API is their programming interface, the functionality that is exposed to the users. If something happens to how this functionality is presented (extended, changed, removed), that is an API change of the SDK. Understanding of the nature of changes might vary between languages & platforms, because e.g. one lang can have types in its API and other could not support types at all. SDKs could not be the same.

Semver is purely focused on incrementing the versions relatively to the nature of an API change, and it is clearly determined except extreme edge cases. I think we should not add any additional rules into it.

Btw, each SDK might consist of multiple packages each with its own version. And they might be different too!

[Mingela]

There is no contradiction with that, I'd just like to highlight that one can expect SDK major increment without any change in Iroha API, but Iroha breaking API change would always come with an SDK version major increment supporting that, wouldn't it?

[0x009922]

but Iroha breaking API change would always come with an SDK version major increment supporting that, wouldn't it?

Most probably yes. Just not sure if it is 100% formally "mathematically" impossible to not have major increment in the SDK in that case.

[0x009922]

Suggested change

	- `PATCH`: Incremented for backward-compatible bug fixes or minor updates in the SDK.
	- `PATCH`: Incremented for backward- and forward-compatible changes (bug fixes, internal refactoring) in the SDK.

[0x009922]

I don't see any benefit from it. Moreover, JS SDK packages are already of major version 6.0.0.

[Mingela]

That's just an example not even a recommendation to follow

[0x009922]

Might be less confusing if we use 3.0.0 or 1.0.0 though.

[dmitrivenger]

I think we still should have some kind of reference to Iroha RC

[0x009922]

Suggested change

	2. Incremental SDK Updates: As we continue to deliver enhancements, features, and bug fixes for Iroha Core `2.0.0`, increment the SDK versions independently of Iroha Core's version. Use `MINOR` and `PATCH` version increments to indicate the level of changes in the SDKs themselves.
	2. Incremental SDK Updates: As we continue to deliver enhancements, features, and bug fixes for Iroha Core `2.0.0`, increment the SDK versions independently of Iroha Core's version. Use `PATCH`, `MINOR`, or `MAJOR` version increments to indicate the level of changes in the SDKs themselves.

[0x009922]

Suggested change

	- `MINOR`: Incremented for backward-compatible features or enhancements in the SDK.
	- `MINOR`: Incremented for backward-compatible changes (new features, extensions of API) in the SDK.

[0x009922]

Suggested change

	- If we make non-breaking enhancements to the Java SDK, we can increment the version to `2.1.0`.
	- For bug fixes or minor updates that don't introduce breaking changes in the SDK, we can increment the version to `2.1.1`.
	- Whenever you release updates, ensure that the documentation clearly states the compatibility of each SDK version with Iroha Core `2.0.0`.
	1. If we add forward-compatible features to the Java SDK, we can increment the version to `2.1.0` (minor update).
	2. For forward- and backward-compatible bug fixes in the SDK, we can increment the version to `2.1.1` (patch update).
	3. If we introduce forward-incompatible breaking changes to the Java SDK for whatever reason, we increment the version to `3.0.0` (major update). It might not necessarily happen on updates of Iroha Core.
	4. If Iroha Core is updated and we update the SDK for it, we still increment the version of the SDK accordingly to the level of changes of the SDK itself.
	5. Whenever you release updates, ensure that the documentation clearly states the compatibility of each SDK version with Iroha Core `2.0.0`.

[Mingela]

@0x009922
Not clear what the difference between the first and the second scenarios is, how about putting forward-compatible to the second scenario (patch)?

It might not necessarily happen on minor updates of Iroha Core.

I'd remove 'minor'.

we have to update the SDK

Sounds like a breaking change. Rather just remove 'have to'.

[0x009922]

@Mingela,

• added numbers to scenarios
• rephrased 1, 2, and 3
• removed "minor"
• removed "have to"

[Mingela]

lgtm

[Mingela]

Suggested change

	- Whenever you release updates, ensure that the documentation clearly states the compatibility of each SDK version with Iroha Core `2.0.0`.
	- Whenever you release updates, ensure that the documentation clearly states the compatibility of each SDK version with corresponding Iroha Core `2.*.*` version.

[0x009922]

If we use semver naming conventions, it would be just 2.*, not 2.*.*. Not invalid, but redundant a bit.

[0x009922]

Currently the RFC only describes how SDK versions are updated according to the updates of the core. This is not the only versioning-related problem we are facing.

Another problem is how we communicate and guide users about the versions they should use. Users should have an easy and accessible way to understand which version of an SDK they should use according to their version of Iroha. This RFC should include basic use-cases and define such a policy for us that will address the documentation problem in the most optimal way.

For example: users might know with which version of Iroha they work, and they need to choose a compatible version of SDK X. Probably, it would be logical for them to go to the main Iroha documentation and find a page related to versioning. On that page they will find a breakdown of versions of each SDK according to a version of Iroha. Or, what might be simpler for us, the page might contain links to SDKs' READMEs with a note that versioning information will be found there. In the meantime, each SDK's README will contain a table/instruction about how to choose a version of the SDK compatible with this or that version of Iroha.

[dmitrivenger]

Documenting Versioning:

• In order to enhance transparency and user understanding, we propose maintaining a comprehensive record of SDK versions in both the "read.me" file and on GitHub. All alterations and updates to the SDK will be meticulously documented, allowing users to easily track and comprehend the evolution of the software. The most recent version information will be prominently displayed in the "read.me" file for quick reference. The old "historical updates" will be stored in the GitHub.

Naming Conventions:

• To eliminate ambiguity and enhance clarity, we commit to abandoning the conventional X.X.X versioning system. Instead, each modification will be explicitly documented, providing users with a more descriptive and meaningful insight into the changes made.

Compatibility Matrix Development:

• We aim to establish a compatibility matrix accessible here. This matrix will serve as a user-friendly guide, outlining the compatibility between different SDK versions, command-line interface (CLI), and iroha core versions. The matrix will be structured as a table, with SDK versions listed in rows and iroha versions in columns. Users will be able to discern, at a glance, which SDK version aligns with a specific iroha core version. This initiative will enhance user experience and simplify decision-making for our community.

@0x009922, @Mingela @mversic and @6r1d please take a look at the summary and kindly let me know if we can styart moving towards creating a robust compatibility matrix. Cheers!

[Mingela]

@dmitrivenger,

Documenting Versioning

README there is referred to Iroha's README, while GitHub refers to the respective SDK Releases description and README file. So, Iroha's README should contain at least a general reference to each of the SDKs while all the details are to be available on the SDK repo side, highlighting the latest version description in the latter's README.

Naming Conventions

We'll actually to stick to X.X.X, we just wouldn't provide any requirements to their consistency between SDKs and/or Iroha Core. Each SDK version should be documented at least in terms of changesets comparing to the previous version and the Iroha Core version reference it's intended to support (or any other forward compatible one).

Compatibility Matrix Development

All good. I'd just say we should maintain 2 types of matrices: SDK x Iroha version correspondence and solely features available in the SDKs (functional comparison of the latest versions of SDKs).