Bump version to 2024.12.3 [skip-versioning]

Fix verison validation

.github/workflows/release_tag.yml

@@ -1,3 +1,11 @@
+# This GitHub Actions workflow updates the "stable" and "latest" Git tags
+# to point to the tag associated with a newly published release. It performs
+# the following steps:
+# 1. Checks out the repository code with full history.
+# 2. Configures Git with a generic user for the action.
+# 3. Moves and forcibly pushes the "stable" and "latest" tags to align with
+#    the tag of the newly published release.
+# This ensures that "stable" and "latest" always point to the most recent release.
 ---
 name: Update Tags
 

.github/workflows/versioning.yml

@@ -1,11 +1,14 @@
-# Workflow for managing versioning, tagging, and conditional updates
+# Workflow for managing versioning and tagging
 ---
-name: Bump Version and Tag
+name: Version Bump and Tag
 
 on:  # yamllint disable-line rule:truthy
   push:
     branches:
       - main
+    paths-ignore:
+      - '**/VERSION'
+      - '**/VERSION_YAML'
   workflow_dispatch:
     inputs:
       update_stable:
@@ -18,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: "actions/checkout@v4"
 
       - name: Set up Git
         run: |
@@ -27,19 +30,13 @@ jobs:
 
       - name: Bump Version
         run: |
-          chmod +x ./versioning/bump_version.sh
+          chmod +x "./versioning/bump_version.sh"
-          ./versioning/bump_version.sh
+          "./versioning/bump_version.sh"
 
       - name: Push Changes and Tags
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
         run: |
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git main
+          git push "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" main
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git --tags
+          git push "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" --tags
-
-      - name: Conditionally Update Stable Tag
-        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.update_stable == 'true' }}
-        run: |
-          git tag -f stable
-          git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git stable --force
 ...

versioning/README.md

@@ -1,35 +1,29 @@
 # Versioning
 
 ## Overview
-This project uses a time-based versioning scheme: `year.month.sequential_number`.
+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.
+The system automates version updates and tagging to ensure consistent, conflict-free management of releases.
 
 ### Examples
-- `2024.12.01` – First release of December 2024.
+- `2024.1.1` – First release of January 2024.
-- `2024.12.02` – Second release of December 2024.
+- `2024.12.2` – Second release of December 2024.
-- `2025.01.01` – First release of January 2025.
 
-## Files
+## How It Works
-- **`VERSION`**: Contains the current version of the project as plain text.
+1. **Temporary Branch Creation**: A unique branch is created for each workflow run.
-- **`bump_version.sh`**: A script to increment the version based on the current date and release sequence.
+2. **Version Update**: The workflow updates the `VERSION` and `VERSION_YAML` files using the current date and release sequence.
-- **`README.md`**: Documentation for the versioning process.
+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`.
-## Versioning Rules
+5. **Branch Cleanup**: The temporary branch is deleted after merging.
-1. The version format is `YYYY.MM.NN`, where:
-   - `YYYY` is the current year.
-   - `MM` is the current month (two digits).
-   - `NN` is the sequential release number within the month (starting at `01`).
-2. On each new merge to the `main` branch:
-   - If the month hasn’t changed, the sequential number (`NN`) is incremented.
-   - If the month has changed, the sequential number resets to `01`.
 
 ## Usage
 
-### Automatically Managed
+### Automated Workflow
-The versioning process is fully integrated into the workflow. Developers do not need to manually increment or manage versions.
+The versioning process is fully automated:
-Simply push your changes, and the system will handle version updates and tagging automatically.
+- 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
@@ -37,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
+## Benefits
-1. **Clarity**: Each version is tied to a specific point in time, making it easy to track releases.
+- **Clarity**: Easily track when a release occurred with meaningful version numbers.
-2. **Automation**: The process is seamless and reduces manual effort.
+- **Automation**: Eliminates manual version management.
-3. **Scalability**: Supports frequent releases while keeping the versioning system organized.
+- **Scalability**: Supports frequent updates and concurrent workflows.
-4. **Traceability**: Git tags and the `VERSION` file ensure releases are well-documented and easily accessible.
+- **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.
+Consider extending the system to:
-- Enhance the `bump_version.sh` script to support different versioning schemes if needed.
+- Automatically generate release notes or changelogs.
-- Integrate versioning information into your deployment pipelines to label builds with their corresponding version.
+- 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:
+**Q: Can I manually update the version?**  
-- Year must be a 4-digit number (YYYY)
+A: Manual updates are not needed. The workflow ensures accurate, automated versioning.
-- 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.

versioning/VERSION

@@ -1 +1 @@
-2024.12.01
+2024.12.3

versioning/VERSION_YAML

@@ -1 +1 @@
-version: 2024.12.01
+version: 2024.12.3

versioning/bump_version.sh

@@ -5,18 +5,20 @@ VERSION_YAML_FILE="./versioning/VERSION_YAML"
 
 # Read the current version
 if [ -f "$VERSION_FILE" ]; then
-  CURRENT_VERSION=$(cat $VERSION_FILE)
+  CURRENT_VERSION=$(cat "$VERSION_FILE")
 else
   CURRENT_VERSION="0.0.0" # Default if file doesn't exist
 fi
 
-# Extract components
+# Validate the current version format
-CURRENT_YEAR=$(date +%Y)
+if ! [[ "$CURRENT_VERSION" =~ ^[0-9]{4}\.[0-9]{1,2}\.[0-9]+$ ]]; then
-CURRENT_MONTH=$(date +%m)
-if ! [[ "$CURRENT_VERSION" =~ ^[0-9]{4}\.[0-9]{2}\.[0-9]{2}$ ]]; then
   echo "Error: Invalid version format in $VERSION_FILE"
   exit 1
 fi
+
+# Extract components
+CURRENT_YEAR=$(date +%Y)
+CURRENT_MONTH=$(date +%-m) # Avoid leading zero for the month
 CURRENT_SEQ=$(echo "$CURRENT_VERSION" | awk -F. '{print $3}')
 
 VERSION_YEAR=$(echo "$CURRENT_VERSION" | awk -F. '{print $1}')
@@ -24,17 +26,12 @@ VERSION_MONTH=$(echo "$CURRENT_VERSION" | awk -F. '{print $2}')
 
 # Determine new version
 if [[ "$CURRENT_YEAR" == "$VERSION_YEAR" && "$CURRENT_MONTH" == "$VERSION_MONTH" ]]; then
-  NEXT_SEQ=$((10#$CURRENT_SEQ + 1))
+  NEXT_SEQ=$((CURRENT_SEQ + 1))
-  if [ $NEXT_SEQ -gt 99 ]; then
-    echo "Error: Sequence number would exceed 99"
-    exit 1
-  fi
-  NEW_SEQ=$(printf "%02d" $NEXT_SEQ)
 else
-  NEW_SEQ="01" # Reset sequence for a new month
+  NEXT_SEQ=1 # Reset sequence for a new month
 fi
 
-NEW_VERSION="${CURRENT_YEAR}.${CURRENT_MONTH}.${NEW_SEQ}"
+NEW_VERSION="${CURRENT_YEAR}.${CURRENT_MONTH}.${NEXT_SEQ}"
 
 # Update the plain text VERSION file
 echo "$NEW_VERSION" > "$VERSION_FILE"
@@ -47,7 +44,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