69 lines
3.0 KiB
Markdown
69 lines
3.0 KiB
Markdown
# 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:
|
||
|
||
```yaml
|
||
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.
|