New versioning

.github/workflows/validate_esphome_beta.yml

@@ -1,8 +1,7 @@
 ---
 name: Validate ESPHome (Beta)
 
-# yamllint disable-line rule:truthy
-on:
+on:  # yamllint disable-line rule:truthy
   push:
     paths:
       - "*.yaml"

.github/workflows/versioning.yml

@@ -0,0 +1,45 @@
+# Workflow for managing versioning, tagging, and conditional updates
+---
+name: Bump Version and Tag
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+    inputs:
+      update_stable:
+        description: "Update stable tag?"
+        required: true
+        default: "false"
+
+jobs:
+  versioning:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Git
+        run: |
+          git config user.name "GitHub Actions"
+          git config user.email "actions@github.com"
+
+      - name: Bump Version
+        run: |
+          chmod +x ./versioning/bump_version.sh
+          ./versioning/bump_version.sh
+
+      - name: Push Changes and Tags
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git push origin main
+          git push origin --tags --force
+
+      - name: Conditionally Update Stable Tag
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.update_stable == 'true' }}
+        run: |
+          git tag -f stable
+          git push origin stable --force
+...

README.md

@@ -98,17 +98,15 @@ TX Ultimate Easy offers extensive configuration options:
 We welcome contributions from the community! Here's how you can help:
 
 1. Fork the repository
-2. Create a feature branch from `dev`
+2. Create a feature branch from `main`
 3. Make your changes
-4. Submit a pull request targeting the `dev` branch
+4. Submit a pull request targeting the `main` branch
 
 Please ensure your code follows our standards:
 - Passes all lint checks (YAML, C++, Markdown)
 - Includes appropriate documentation
 - Follows existing code style
 
-All pull requests should be made against the `dev` branch. We don't accept pull requests directly to `main` as it's reserved for stable releases.
-
 ## Support and Community
 
 Need help? Here are your options:

versioning/README.md

@@ -0,0 +1,55 @@
+# 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.12.01` – First release of December 2024.
+- `2024.12.02` – Second release of December 2024.
+- `2025.01.01` – First release of January 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.
+
+## Versioning Rules
+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
+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.
+
+### 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/bump_version.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+
+VERSION_FILE="./versioning/VERSION"
+VERSION_YAML_FILE="./versioning/VERSION_YAML"
+
+# Read the current version
+if [ -f "$VERSION_FILE" ]; then
+  CURRENT_VERSION=$(cat $VERSION_FILE)
+else
+  CURRENT_VERSION="0.0.0" # Default if file doesn't exist
+fi
+
+# Extract components
+CURRENT_YEAR=$(date +%Y)
+CURRENT_MONTH=$(date +%m)
+CURRENT_SEQ=$(echo "$CURRENT_VERSION" | awk -F. '{print $3}')
+
+VERSION_YEAR=$(echo "$CURRENT_VERSION" | awk -F. '{print $1}')
+VERSION_MONTH=$(echo "$CURRENT_VERSION" | awk -F. '{print $2}')
+
+# Determine new version
+if [[ "$CURRENT_YEAR" == "$VERSION_YEAR" && "$CURRENT_MONTH" == "$VERSION_MONTH" ]]; then
+  NEW_SEQ=$(printf "%02d" $((10#$CURRENT_SEQ + 1))) # Increment sequence
+else
+  NEW_SEQ="01" # Reset sequence for a new month
+fi
+
+NEW_VERSION="${CURRENT_YEAR}.${CURRENT_MONTH}.${NEW_SEQ}"
+
+# Update the plain text VERSION file
+echo "$NEW_VERSION" > "$VERSION_FILE"
+
+# Update the YAML VERSION_YAML file
+echo "version: $NEW_VERSION" > "$VERSION_YAML_FILE"
+
+# Commit and tag
+git add "$VERSION_FILE" "$VERSION_YAML_FILE"
+git commit -m "Bump version to $NEW_VERSION"
+git tag "v$NEW_VERSION"