TX-Ultimate-Easy/versioning

Versioning

Overview

This project uses a time-based versioning scheme: year.month.sequential_number. This scheme makes it easy to identify when a version was released and provides a clear order for releases within a given month.

Examples

• 2024.1.1 – First release of January 2024.
• 2024.12.2 – Second release of December 2024.
• 2025.3.1 – First release of March 2025.

Files

• VERSION: Contains the current version of the project as plain text.
• bump_version.sh: A script to increment the version based on the current date and release sequence.
• README.md: Documentation for the versioning process.

Version Validation

The versioning system enforces strict format validation:

• Year must be a 4-digit number (YYYY)
• Month must be a number from 1 to 12 without leading zeros
• Sequence must be a positive number with no leading zeros (1, 2, ...).

The bump_version.sh script includes validation checks and will fail if:

• The version format is invalid.
• Other format-related issues are detected.

Usage

Automatically Managed

The versioning process is fully integrated into the workflow. Developers do not need to manually increment or manage versions. Simply push your changes, and the system will handle version updates and tagging automatically.

Access Version in Code

The version is accessible in the ESPHome YAML configuration file (TX-Ultimate-Easy-ESPHome_core.yaml) using the following syntax:

substitutions:
  version: <<: !include ../versioning/VERSION

This ensures the correct version is used directly in the ESPHome setup without requiring manual updates.

Benefits of this Versioning Approach

1. Clarity: Each version is tied to a specific point in time, making it easy to track releases.
2. Automation: The process is seamless and reduces manual effort.
3. Scalability: Supports frequent releases while keeping the versioning system organized.
4. Traceability: Git tags and the VERSION file ensure releases are well-documented and easily accessible.

Extending the System

• Add more scripts to handle additional automation tasks, such as generating changelogs or notifying stakeholders of new releases.
• Enhance the bump_version.sh script to support different versioning schemes if needed.
• Integrate versioning information into your deployment pipelines to label builds with their corresponding version.

Version Validation

The versioning system enforces strict format validation:

• Year must be a 4-digit number (YYYY)
• Month must be a 2-digit number (01-12)
• Sequence must be a 2-digit number (01-99)

The bump_version.sh script includes validation checks and will fail if:

• The version format is invalid
• The sequence number would exceed 99 in a month

GitHub Actions Workflow Adjustment

The GitHub Actions workflow for versioning runs only when changes are merged into the main branch, ensuring no premature version updates during PR creation. This behavior is automatically handled by the integrated workflow.