Skip to content

Feature: SDK versioning document #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
6r1d wants to merge 8 commits into
base: main
Choose a base branch
from
+33 −0
Open

Feature: SDK versioning document #10

Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
5528bcd
featute: SDK versioning document
6r1d Oct 11, 2023
1bf3e10
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
fd53f77
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
0131c06
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
a781254
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
91c9ce8
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
ac724f0
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
1769715
Update 008-sdk-versioning.md
6r1d Oct 12, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions 008-sdk-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
## Revised SDK Versioning Strategy for Iroha Core

### Semantic Versioning

The SDKs will continue to follow semantic versioning with `MAJOR.MINOR.PATCH`. However, the meaning of each part will be related to the current delivery strategy of the Iroha 2 Core.

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

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

@Mingela Mingela Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

Copy link
Member

@Mingela Mingela Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor

@0x009922 0x009922 Oct 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- `MINOR`: Incremented for backward-compatible features or enhancements in the SDK.
Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

- `PATCH`: Incremented for backward-compatible bug fixes or minor updates in the SDK.
Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


### Relationship with Iroha Core

1. Initial Compatibility: Initially, set the SDK versions to align with Iroha Core `20.0.0`, reflecting the current release. For example, the SDKs might start at `2.0.0`.
Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

@Mingela Mingela Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link

@dmitrivenger dmitrivenger Nov 13, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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.
Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


3. Documentation Updates: Continuously update the documentation to specify which version of Iroha Core your SDK versions are compatible with. This information should be prominently displayed for users to reference.

### Versioning Example

Let's say we have a Java SDK initially at version `2.0.0`, which aligns with Iroha Core `20.0.0`.

- 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`.
Comment on lines +23 to +27
Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`.

Copy link
Member

@Mingela Mingela Oct 12, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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'.

Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Mingela,

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

Copy link
Member

@Mingela Mingela Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm

Copy link
Member

@Mingela Mingela Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@0x009922 0x009922 Oct 12, 2023

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### Continuous SDK Development

This strategy allows our SDKs to continue evolving and improving while keeping compatibility with Iroha Core `2.0.0`. By using `MINOR` and `PATCH` version increments, we can convey the level of changes within each SDK release. Make sure to maintain clear and up-to-date documentation to assist users in choosing the appropriate SDK version for their needs, considering compatibility with Iroha Core `2.0.0`.