Merge branch 'main' into new-versioning-03

.github/workflows/versioning.yml

@@ -28,12 +28,18 @@ jobs:
           git config user.name "GitHub Actions"
           git config user.email "[email protected]"
 
+      - 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: |

versioning/README.md

@@ -1,57 +1,76 @@
 # 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
 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.
 
-## 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.
+## 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.
 
-## Version Validation
+If validation fails, the workflow stops and provides an error message.
 
-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, ...).
+### 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
+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.
 
-The `bump_version.sh` script includes validation checks and will fail if:
-- The version format is invalid.
-- Other format-related issues are detected.
+## FAQ
+**Q: What happens if two workflows run concurrently?**  
+A: Each workflow operates in its own temporary branch, avoiding conflicts.
 
-### 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.

versioning/VERSION

@@ -1 +1 @@
-2024.12.01
+2024.12.1

versioning/bump_version.sh

@@ -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