diff --git a/.github/workflows/versioning.yml b/.github/workflows/versioning.yml index 9f5f371..97de6ad 100644 --- a/.github/workflows/versioning.yml +++ b/.github/workflows/versioning.yml @@ -1,11 +1,14 @@ -# Workflow for managing versioning, tagging, and conditional updates +# Workflow for managing versioning, tagging, and temporary branches --- -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: @@ -25,21 +28,35 @@ 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: | - git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git main - git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git --tags - - - name: Conditionally Update Stable Tag - if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.update_stable == 'true' }} + git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" HEAD + - name: Merge Changes into Main + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - git tag -f stable - git push https://x-access-token:${GITHUB_TOKEN}@github.com/edwardtfn/TX-Ultimate-Easy.git stable --force + git checkout main + git pull "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" main + git merge --no-ff "$TEMP_BRANCH" -m "Automated Version Bump [skip-versioning]" + git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" main + + - name: Delete Temporary Branch + if: always() + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" --delete "$TEMP_BRANCH" ... diff --git a/versioning/README.md b/versioning/README.md index 49ea543..9c5ded7 100644 --- a/versioning/README.md +++ b/versioning/README.md @@ -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. diff --git a/versioning/VERSION b/versioning/VERSION index 9550c9e..d969417 100644 --- a/versioning/VERSION +++ b/versioning/VERSION @@ -1 +1 @@ -2024.12.01 +2024.12.1 diff --git a/versioning/bump_version.sh b/versioning/bump_version.sh index 3b85e58..5693c61 100644 --- a/versioning/bump_version.sh +++ b/versioning/bump_version.sh @@ -42,7 +42,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