[DISCUSSION] Release Version Number and Schedule

[DemesneGH]

[DISCUSSION] Release Version Number and Schedule

Hi all,

We are currently preparing for a new release and need more clarity about the release plan. We would greatly appreciate your thoughts and suggestions to help us establish a more concrete and reasonable release scheme.

1. Upcoming Release Version Number

Given the significant changes introduced since the previous release (v0.3.0-rc1), including breaking changes to the build environment, we are considering two options for the upcoming release version number:

• Option 1: Release as v0.3.0-rc2, which means a normal upgrade, will later be finalized as v0.3.0 after the Apache release process.
• Option 2: Bump the version to v1.0.0, marking this release as a major milestone.

Both choices have different considerations, taking v0.3.0 as default, let's discuss about moving to v1.0.0.

YES because:

• According to Semantic Versioning, a major version should be incremented when there are incompatible API changes. Our build environment refactoring introduces significant breaking changes that are not compatible with the legacy setup.
• This release includes more substantial changes compared to any previous release and potentially future releases in the near term (more details on the appended Release Notes). Labeling it as v1.0.0 highlights it as a major milestone rather than just an incremental upgrade.
• Following OP-TEE's approach—where they bumped from 3.x to 4.x due to compatibility changes, including APIs and tools, we can align with their versioning strategy.

NO because:

• In the Rust ecosystem, a v1.0.0 release often implies stability and production readiness. Many Rust crates (e.g., Rustls) maintain 0.x versions even with breaking changes to indicate ongoing development. Should we continue with minor version increments until we achieve broader adoption and maturity?
• While the build environment has undergone significant changes, there haven't been major API modifications.

2. Release Schedule

OP-TEE follows a quarterly release schedule for minor versions and introduces major versions when there are incompatible API changes. For major versions we've discussed on topic 1. In this part let's talk about normal releases (minor versions):

What should be the release schedule?

• Align with OP-TEE's quarterly schedule?
  • As the recommended Rust SDK for OP-TEE, synchronizing our releases could enhance alignment and compatibility.
• Follow an independent schedule?
  • Since OP-TEE upgrades do not always directly impact the Rust SDK, we could adopt our own release schedule based on our development needs. The challenge lies in determining an effective and practical schedule.

If you have any recommendations, feel free to comment on this thread, thanks!

---

For reference, I've prepared the draft Release Notes for the upcoming release:

Apache Teaclave TrustZone SDK (incubating) vx.x.x Release Notes

This release introduces a new unified build environment that supports both the original std and the newly added no-std, along with a new crate to simplify the process of building trusted applications. It also includes real-world examples and updates to support the latest OP-TEE release (4.5.0).

The following are the key updates since v0.3.0-rc1:

Breaking Changes in the Build Environment

In this release candidate, we have reorganized the code structure and build environment to support both no-std and std build options, simplifying the overall build process.

Additionally, the TA build scripts have been streamlined by introducing the new optee-utee-build crate.

Since the process is quite complex, the following breakdown provides more details:

Starting with an intermediate branch no-std, which simplifies the build environment from scratch:

• On no-std branch: Cleaned up the build environment for no-std and simplified the build process. The works processed on PR114-PR122, e.g.: PR #115
• Based on no-std, added std support: PR #141
• Renamed no-std to main and set it as the default branch: Issue #143
• Further improvements on main after setting it as default:
  Introduced optee-utee-build crate for simplified TA builds. PR #156

Integration with OP-TEE

• Updated CI Docker image for the new OP-TEE build environment: PR #157
• Pinned the setup to OP-TEE 4.5.0: Commit 3aa0c94

New Features

• Made panic_handler optional in optee-utee: PR #147
• Added support for configuring the capacity of shared buffers in LoadablePlugin: PR #154
• Added no-std networking support in optee-utee: PR #164

New Examples

• Added error-handling example: PR #127
• Introduced project/ directory for real-world examples, including a Web3 ETH wallet example: PR #150
• Added no-std support for tcp_client-rs and udp_socket-rs. PR #164

Bug Fixes

• Fixed a double-free bug in optee-utee: PR #127
• Improved argument validation error messages: PR #134

Documentation Updates

• README updates:
  • no-std improvements: PR #128
  • Re-added std support in the new build environment: PR #144
• New migration guide:
  • Migrating to the new build environment (Post-Oct 2024)
• Guide for writing Rust TAs using optee-utee-build:
  • Writing Rust TAs

[b49020]

Thanks @DemesneGH for putting up a proposal for the new release.

• Option 1: Release as v0.3.0-rc2, which means a normal upgrade, will later be finalized as v0.3.0 after the Apache release process.
• Option 2: Bump the version to v1.0.0, marking this release as a major milestone.

How about Option 3 instead as follows?

• Option 3: Release as v0.4.0, indicating as a major development step. As we see further adoption of Rust based TAs in production environments then only we will be able to know their stability.

Align with OP-TEE's quarterly schedule?

• As the recommended Rust SDK for OP-TEE, synchronizing our releases could enhance alignment and compatibility.

This option sounds better to remain aligned with OP-TEE releases. We can do releases in say 1 week cadence with OP-TEE releases with a minor version bump say for example v0.4.0 => v0.4.1 for the next OP-TEE v4.6.0 release and so on. Also, please publish corresponding releases on crates.io accordingly.

[DemesneGH]

• Option 3: Release as v0.4.0, indicating as a major development step. As we see further adoption of Rust based TAs in production environments then only we will be able to know their stability.

I agree with you. Let's make the next release 0.4.0. However, since 0.3.0-rc1 did not complete the Apache release process, we may have to keep it as rc1 for now.

We can do releases in say 1 week cadence with OP-TEE releases with a minor version bump say for example v0.4.0 => v0.4.1 for the next OP-TEE v4.6.0 release and so on.

The version format follows MAJOR.MINOR.PATCH, it's good to sync with OP-TEE's release plan but I'm not sure whether to increment the MINOR or PATCH number. Would the MINOR number be more reasonable? (which means v0.5.0 for OP-TEE v4.6.0)

[b49020]

• Option 3: Release as v0.4.0, indicating as a major development step. As we see further adoption of Rust based TAs in production environments then only we will be able to know their stability.

I agree with you. Let's make the next release 0.4.0. However, since 0.3.0-rc1 did not complete the Apache release process, we may have to keep it as rc1 for now.

Okay that's fine with me.

We can do releases in say 1 week cadence with OP-TEE releases with a minor version bump say for example v0.4.0 => v0.4.1 for the next OP-TEE v4.6.0 release and so on.

The version format follows MAJOR.MINOR.PATCH, it's good to sync with OP-TEE's release plan but I'm not sure whether to increment the MINOR or PATCH number. Would the MINOR number be more reasonable? (which means v0.5.0 for OP-TEE v4.6.0)

Sounds reasonable to me.

[DemesneGH]

Thanks for all comments on this thread. Considering Rust's best practices, Apache release processes, OP-TEE’s schedule, and user-friendliness, I propose the following release versioning and schedule:

Versioning Strategy

Version Bump

• optee-* crates**: All optee-related crates (crates.io search) located in optee-utee/, optee-teec/, optee-utee-build/ will have synchronized versions and be updated simultaneously.

  • Bump criteria: (quarterly check) && (code changes in any of the optee-* crate source code)

• Examples/Projects: Will be versioned separately and updated independently when their respective code changes.

Release Process

optee Rust Crates Release

• The optee Rust crates will be published on crates.io.
• A new version will be released only when new features, fixes, or OP-TEE compatibility adjustments require code changes.
• To ensure clarity and encourage synchronized usage, all optee-* crates (crates.io search) will have their versions bumped together, even if some remain unchanged.

Apache Release for the Entire Repository (follow the Teaclave Release Guide)

• An Apache release will be made only when a new optee-* Rust crate version is published.
• The Apache release version will always align with the optee-* crates version number.
• The source code for all repositories will be packaged and made available in GitHub Releases.
• A release note will be included.
• The release process will follow voting procedures within the Teaclave community and the Apache Incubator.

Release Schedule

Quarterly Release Check

• One week after OP-TEE releases a new version, we will verify compatibility with the latest OP-TEE release.
• If any optee-* Rust crates require updates for compatibility, or have updated after the previous release, a new release will be published after the necessary code updates, and the version numbers will be incremented accordingly.
• If there are no code changes in the optee-* crates (e.g., only examples/projects are updated), no new release will be made to avoid redundant version bumps.

Release Record Table

To maintain transparency and clarity, we will maintain a table in the main README to track release versions and their corresponding OP-TEE versions:

Apache Teaclave SDK Release Version	optee-* Rust crate Release version	OP-TEE Version	OP-TEE Release Date	Check for Teaclave SDK Release
-	-	OP-TEE 4.8.0	17/Oct/25	31/Oct/25
-	-	OP-TEE 4.7.0	11/Jul/25	25/Jul/25
-	-	OP-TEE 4.6.0	11/Apr/25	25/Apr/25
v0.4.0	v0.4.0	OP-TEE 4.5.0	17/Jan/25	17/Feb/25

Example Scenario

If there are no changes to optee-* crates between OP-TEE 4.5.0 and 4.6.0, but changes are made before OP-TEE 4.7.0, the table will appear as follows:

Apache Teaclave SDK Release Version	optee-* Rust crate Release version	OP-TEE Version	OP-TEE Release Date	Date of Check for Teaclave SDK Release
-	-	OP-TEE 4.8.0	17/Oct/25	31/Oct/25
v0.5.0	v0.5.0	OP-TEE 4.7.0	11/Jul/25	25/Jul/25
v0.4.0 (no new release, skipped)	v0.4.0 (no new release, skipped)	OP-TEE 4.6.0	11/Apr/25	25/Apr/25
v0.4.0	v0.4.0	OP-TEE 4.5.0	17/Jan/25	17/Feb/25

Let's dicuss this proposal, please feel free to comment on this thread, thanks!

[b49020]

Sounds reasonable to me.