1.5. Standards: Semantic Versioning and Testing Suite Alignment

Semantic Versioning and Testing Suite Alignment

This document outlines how to use semantic versioning SemVer in conjunction with a the testing suite strategy. We'll follow the major.minor.bugfix/doc format and establish clear guidelines for versioning and testing.

Semantic Versioning (SemVer)

SemVer is a widely adopted versioning system that uses a three-part version number: MAJOR.MINOR.BUGFIX.

• MAJOR: Increased when you make incompatible API changes.
• MINOR: Increased when you add functionality in a backwards-compatible manner.
• BUGFIX/DOC: Increased when you make backwards-compatible bug fixes or documentation upgrades.

Versioning Guidelines

1. Interface Extension:

   • If you extend an interface without requiring the caller to rebuild, it's a MINOR change.
   • If the caller needs to rebuild due to the interface extension, it's a MAJOR change.

2. Bug Fixes and Documentation:

   • Bug fixes and documentation changes are considered BUGFIX or DOC changes, respectively.

Testing Suite Alignment

1. Major and Minor Alignment:

   • Testing suites should be aligned with MAJOR.MINOR versions.
   • Each testing suite should comprehensively test all functions within that specific MAJOR.MINOR version.

2. Bugfix/Doc Update Ingestion:

   • BUGFIX and DOC upgrades should be automatically ingested into the testing suite to ensure compatibility with the existing interface.

3. Minor Upgrade and Testing Suite:

   • When a MINOR upgrade introduces new functionality, the corresponding testing suite must also be upgraded to support and test that new functionality.

4. Testing Suite Cloning:

   • Testing suites should be cloned and aligned with MAJOR.MINOR versions to maintain separate test coverage for each distinct interface.

UT-Core Template Scripts and Version Selection

UT-Core template scripts allow for selecting the new version before the testing suite is released.

• The HALIF build_ut.sh script automatically selects the next highest version number.
• This enables releases with a fixed tag ahead of testing suite implementation.
• Testing suites must be selected via tags, facilitating a streamlined release process.

Example Workflow: HAL Interface Upgrade

1. Development: You add a new backwards-compatible feature to your HAL interface.
2. Versioning: Increment the MINOR version (e.g., from 1.2.5 to 1.3.0).
3. Testing Suite: Prepare the corresponding testing suite (e.g., 1.3.x) to include tests for the new feature. This might involve creating a new branch or updating configuration files. (The testing suite itself will be released later.)
4. Release:
   • Release the new version (1.3.0) of your HAL interface.
   • Update the build_ut.sh script in the HAL implementation to set UT_PROJECT_VERSION="1.3.". This ensures that when the 1.3.x testing suite is released, it will be automatically selected.

Example Workflow: HAL Testing Suite Upgrade

1. Development: Develop new functions or upgrades for the testing suite to accommodate the new features in the released HAL interface (e.g., 1.3.0).
2. Versioning: Increment the MINOR version of the testing suite (e.g., from 1.2.x to 1.3.0).
3. Release: Release the new version of your testing suite (1.3.0). The build_ut.sh scripts in the HAL implementation, which were previously updated to UT_PROJECT_VERSION="1.3.", will now automatically select this new testing suite version.

Example Workflow: Bug Fix in Testing Suite

1. Bug Fix: You discover and fix a bug in the released testing suite.
2. Versioning: Increment the BUGFIX version of the testing suite (e.g., from 1.3.0 to 1.3.1).
3. Release: Release the bug fix version of the testing suite. The build_ut.sh scripts will automatically use this updated version.

Benefits of this Approach

• Clear Versioning: Ensures consistent and predictable versioning practices.
• Comprehensive Testing: Guarantees thorough testing of all functionalities for each interface version.
• Streamlined Release Process: Facilitates efficient release cycles with automated version selection and testing suite alignment.
• Improved Code Quality: Reduces the risk of regressions and ensures compatibility across versions.