Merge branch 'main' into new-versioning-03
This commit is contained in:
Edward Firmo
8
.github/workflows/versioning.yml
vendored
8
.github/workflows/versioning.yml
vendored
@@ -28,12 +28,18 @@ jobs:
|
||||
git config user.name "GitHub Actions"
|
||||
git config user.email "actions@github.com"
|
||||
|
||||
- name: Create Temporary Branch
|
||||
run: |
|
||||
TEMP_BRANCH="temp/version-bump-$(uuidgen)"
|
||||
echo "TEMP_BRANCH=${TEMP_BRANCH}" >> "${GITHUB_ENV}"
|
||||
git checkout -b "${TEMP_BRANCH}"
|
||||
|
||||
- name: Bump Version
|
||||
run: |
|
||||
chmod +x "./versioning/bump_version.sh"
|
||||
"./versioning/bump_version.sh"
|
||||
|
||||
- name: Push Changes and Tags
|
||||
- name: Push Changes to Temporary Branch
|
||||
env:
|
||||
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
|
||||
run: |
|
||||
|
||||
@@ -1,26 +1,29 @@
|
||||
# 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.
|
||||
This project uses a time-based versioning scheme: `year.month.sequential_number`.
|
||||
The system automates version updates and tagging to ensure consistent, conflict-free management of releases.
|
||||
|
||||
### 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.
|
||||
## How It Works
|
||||
1. **Temporary Branch Creation**: A unique branch is created for each workflow run.
|
||||
2. **Version Update**: The workflow updates the `VERSION` and `VERSION_YAML` files using the current date and release sequence.
|
||||
3. **Commit with Marker**: Changes are committed with a `[skip-versioning]` marker to prevent triggering the workflow again.
|
||||
4. **Merge into Main**: The temporary branch is merged into `main`.
|
||||
5. **Branch Cleanup**: The temporary branch is deleted after merging.
|
||||
|
||||
## 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.
|
||||
### Automated Workflow
|
||||
The versioning process is fully automated:
|
||||
- Developers submit their changes as usual.
|
||||
- The workflow handles version updates, tagging, and integration into `main`.
|
||||
- No manual intervention is needed for versioning.
|
||||
|
||||
### Access Version in Code
|
||||
### Accessing the Version in Code
|
||||
The version is accessible in the ESPHome YAML configuration file (`TX-Ultimate-Easy-ESPHome_core.yaml`) using the following syntax:
|
||||
|
||||
```yaml
|
||||
@@ -28,30 +31,46 @@ substitutions:
|
||||
version: <<: !include ../versioning/VERSION
|
||||
```
|
||||
|
||||
This ensures the correct version is used directly in the ESPHome setup without requiring manual updates.
|
||||
This ensures the correct version is dynamically included in the ESPHome setup.
|
||||
|
||||
## 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.
|
||||
## Benefits
|
||||
- **Clarity**: Easily track when a release occurred with meaningful version numbers.
|
||||
- **Automation**: Eliminates manual version management.
|
||||
- **Scalability**: Supports frequent updates and concurrent workflows.
|
||||
- **Traceability**: Maintains a clear history of changes through Git tags and version files.
|
||||
|
||||
## System Details
|
||||
|
||||
### Version Format
|
||||
The format `year.month.sequential_number` includes:
|
||||
- `year` (YYYY): A 4-digit number representing the year.
|
||||
- `month` (M): A number from 1 to 12 (no leading zeros).
|
||||
- `sequential_number`: A positive number incremented with each release in the same month.
|
||||
|
||||
### Validation Rules
|
||||
The `bump_version.sh` script enforces strict validation:
|
||||
- Year must be a 4-digit number.
|
||||
- Month must be 1–12 without leading zeros.
|
||||
- Sequence must be a positive number without leading zeros.
|
||||
|
||||
If validation fails, the workflow stops and provides an error message.
|
||||
|
||||
### GitHub Workflow
|
||||
The workflow is triggered automatically when:
|
||||
- Changes are pushed to `main`.
|
||||
- Developers trigger it manually using the `workflow_dispatch` event.
|
||||
|
||||
The workflow avoids infinite loops by committing changes with the `[skip-versioning]` marker.
|
||||
|
||||
## 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.
|
||||
Consider extending the system to:
|
||||
- Automatically generate release notes or changelogs.
|
||||
- Notify stakeholders when a new version is released.
|
||||
- Integrate versioning information into deployment pipelines.
|
||||
|
||||
## Version Validation
|
||||
## FAQ
|
||||
**Q: What happens if two workflows run concurrently?**
|
||||
A: Each workflow operates in its own temporary branch, avoiding conflicts.
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
**Q: Can I manually update the version?**
|
||||
A: Manual updates are not needed. The workflow ensures accurate, automated versioning.
|
||||
|
||||
@@ -1 +1 @@
|
||||
2024.12.01
|
||||
2024.12.1
|
||||
|
||||
@@ -47,7 +47,7 @@ if ! git add "$VERSION_FILE" "$VERSION_YAML_FILE"; then
|
||||
echo "Error: Failed to stage version files"
|
||||
exit 1
|
||||
fi
|
||||
if ! git commit -m "Bump version to $NEW_VERSION"; then
|
||||
if ! git commit -m "Bump version to $NEW_VERSION [skip-versioning]"; then
|
||||
echo "Error: Failed to commit version bump"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
Reference in New Issue
Block a user