chore: automate development version and release generation (#772)

This change introduces a GitHub Action to automate release creation, including
proper tagging and automatic addition of a development marker to the version.

A hash is also appended to development versions to make their state easier to
distinguish.

Tests and release documentation have been updated to reflect the revised
release workflow. Several files now retrieve the current version dynamically.

The test --full-run option has been rename to --finalize to make
clear it is to do commit finalization testing.

Signed-off-by: Bobby Noelte <b0661n0e17e@gmail.com>

docs/_generated/configexample.md

@@ -92,7 +92,7 @@
            }
        },
        "general": {
-           "version": "0.2.0+dev",
+           "version": "0.2.0+dev.4dbc2d",
            "data_folder_path": null,
            "data_output_subpath": "output",
            "latitude": 52.52,

docs/_generated/configgeneral.md

@@ -28,7 +28,7 @@ Properties:
 | latitude | `EOS_GENERAL__LATITUDE` | `Optional[float]` | `rw` | `52.52` | Latitude in decimal degrees, between -90 and 90, north is positive (ISO 19115) (°) |
 | longitude | `EOS_GENERAL__LONGITUDE` | `Optional[float]` | `rw` | `13.405` | Longitude in decimal degrees, within -180 to 180 (°) |
 | timezone | | `Optional[str]` | `ro` | `N/A` | None |
-| version | `EOS_GENERAL__VERSION` | `str` | `rw` | `0.2.0+dev` | Configuration file version. Used to check compatibility. |
+| version | `EOS_GENERAL__VERSION` | `str` | `rw` | `0.2.0+dev.4dbc2d` | Configuration file version. Used to check compatibility. |
 :::
 <!-- pyml enable line-length -->
 
@@ -40,7 +40,7 @@ Properties:
 ```json
    {
        "general": {
-           "version": "0.2.0+dev",
+           "version": "0.2.0+dev.4dbc2d",
            "data_folder_path": null,
            "data_output_subpath": "output",
            "latitude": 52.52,
@@ -58,7 +58,7 @@ Properties:
 ```json
    {
        "general": {
-           "version": "0.2.0+dev",
+           "version": "0.2.0+dev.4dbc2d",
            "data_folder_path": null,
            "data_output_subpath": "output",
            "latitude": 52.52,

docs/_generated/openapi.md

@@ -1,6 +1,6 @@
 # Akkudoktor-EOS
 
-**Version**: `v0.2.0+dev`
+**Version**: `v0.2.0+dev.4dbc2d`
 
 <!-- pyml disable line-length -->
 **Description**: This project provides a comprehensive solution for simulating and optimizing an energy system based on renewable energy sources. With a focus on photovoltaic (PV) systems, battery storage (batteries), load management (consumer requirements), heat pumps, electric vehicles, and consideration of electricity price data, this system enables forecasting and optimization of energy flow and costs over a specified period.

docs/conf.py

@@ -7,13 +7,20 @@ https://www.sphinx-doc.org/en/master/usage/configuration.html
 import sys
 from pathlib import Path
 
+# Add the src directory to sys.path so Sphinx can import akkudoktoreos
+PROJECT_ROOT = Path(__file__).parent.parent
+SRC_DIR = PROJECT_ROOT / "src"
+sys.path.insert(0, str(SRC_DIR))
+
+from akkudoktoreos.core.version import __version__
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "Akkudoktor EOS"
-copyright = "2024, Andreas Schmitz"
+copyright = "2025, Andreas Schmitz"
 author = "Andreas Schmitz"
-release = "0.0.1"
+release = __version__
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/develop/develop.md

@@ -393,6 +393,13 @@ At a minimum, you should run the module tests:
         make test
 ```
 
+:::{admonition} Note
+:class: Note
+Depending on your changes you may also have to change the version.py and documentation files. Do as
+suggested by the tests. You may ignore the version.py and documentation changes up until you
+finalize your change.
+:::
+
 You should also run the system tests. These include additional tests that interact with real
 resources:
 

docs/develop/release.md

@@ -13,8 +13,8 @@ and how to set a **development version** after the release.
 | 1    | Contributor | Prepare a release branch **in your fork** using Commitizen |
 | 2    | Contributor | Open a **Pull Request to upstream** (`Akkudoktor-EOS/EOS`) |
 | 3    | Maintainer  | Review and **merge the release PR** |
-| 4    | Maintainer  | Create the **GitHub Release and tag** |
-| 5    | Maintainer  | Set the **development version marker** via a follow-up PR |
+| 4    | CI  | Create the **GitHub Release and tag** |
+| 5    | CI  | Set the **development version marker** via a follow-up PR |
 
 ## 🔄 Detailed Workflow
 
@@ -40,24 +40,26 @@ git checkout -b release/vX.Y.Z
 
 #### Bump the version information
 
-At least update
+Set `__version__` in src/akkudoktoreos/core/version.py
 
-- pyproject.toml
-- src/akkudoktoreos/core/version.py
-- src/akkudoktoreos/data/default.config.json
-- Makefile
+```python
+__version__ = 0.3.0
+```
+
+Prepare version by updating versioned files, e.g.:
+
+- haaddon/config.yaml
 
 and the generated documentation:
 
 ```bash
-make bump VERSION=0.1.0+dev NEW_VERSION=X.Y.Z
-make gen-docs
+make prepare-version
 ```
 
-You may check the changes by:
+Check the changes by:
 
 ```bash
-git diff
+make test-version
 ```
 
 #### Create a new CHANGELOG.md entry
@@ -66,19 +68,20 @@ Edit CHANGELOG.md
 
 #### Create the new release commit
 
+Add all the changed version files and all other changes to the commit.
+
 ```bash
-git add pyproject.toml src/akkudoktoreos/core/version.py \
-    src/akkudoktoreos/data/default.config.json Makefile CHANGELOG.md
-git commit -s -m "chore(release): Release vX.Y.Z"
+git add src/akkudoktoreos/core/version.py CHANGELOG.md ...
+git commit -s -m "chore: Prepare Release v0.3.0"
 ```
 
 #### Push the branch to your fork
 
 ```bash
-git push --set-upstream origin release/vX.Y.Z
+git push --set-upstream origin release/v0.3.0
 ```
 
-### 2️⃣ Contributor: Open the Release Pull Request
+### 2️⃣ Contributor: Open the Release Preparation Pull Request
 
 | From                                 | To                        |
 | ------------------------------------ | ------------------------- |
@@ -87,13 +90,13 @@ git push --set-upstream origin release/vX.Y.Z
 **PR Title:**
 
 ```text
-chore(release): release vX.Y.Z
+chore: prepare release vX.Y.Z
 ```
 
 **PR Description Template:**
 
 ```markdown
-## Release vX.Y.Z
+## Prepare Release vX.Y.Z
 
 This pull request prepares release **vX.Y.Z**.
 
@@ -119,94 +122,26 @@ See `CHANGELOG.md` for full details.
 **Merge Strategy:**
 
 - Prefer **Merge Commit** (or **Squash Merge**, per project preference)
-- Use commit message: `chore(release): Release vX.Y.Z`
+- Use commit message: `chore: Prepare Release vX.Y.Z`
 
-### 4️⃣ Maintainer: Publish the GitHub Release
+### 4️⃣ CI: Publish the GitHub Release
 
-1. Go to **GitHub → Releases → Draft a new release**
-2. **Choose tag** → enter `vX.Y.Z` (GitHub creates the tag on publish)
-3. **Release title:** `vX.Y.Z`
-4. **Paste changelog entry** from `CHANGELOG.md`
-5. Optionally enable **Set as latest release**
-6. Click **Publish release** 🎉
+The new release will automatically be published by the GitHub CI action.
 
-### 5️⃣ Maintainer: Prepare the Development Version Marker
+See `.github/workflwows/bump-version.yml`for details.
 
-**Sync local copy:**
+### 5️⃣ CI: Prepare the Development Version Marker
 
-```bash
-git fetch eos
-git checkout main
-git pull eos main
-```
+The development version marker will automatically be set by the GitHub CI action.
 
-**Create a development version branch:**
-
-```bash
-git checkout -b release/vX.Y.Z_dev
-```
-
-**Set development version marker manually:**
-
-```bash
-make bump VERSION=X.Y.Z NEW_VERSION=X.Y.Z+dev
-make gen-docs
-```
-
-```bash
-git add pyproject.toml src/akkudoktoreos/core/version.py \
-    src/akkudoktoreos/data/default.config.json Makefile
-git commit -s -m "chore: set development version marker X.Y.Z+dev"
-```
-
-```bash
-git push --set-upstream origin release/vX.Y.Z_dev
-```
-
-### 6️⃣ Maintainer (or Contributor): Open the Development Version PR
-
-| From                                     | To                        |
-| ---------------------------------------- | ------------------------- |
-| `<your-username>/EOS:release/vX.Y.Z_dev` | `Akkudoktor-EOS/EOS:main` |
-
-**PR Title:**
-
-```text
-chore: development version vX.Y.Z+dev
-```
-
-**PR Description Template:**
-
-```markdown
-## Development version vX.Y.Z+dev
-
-This pull request marks the repository as back in active development.
-
-### Changes
-- Set version to `vX.Y.Z+dev`
-
-No changelog entry is needed.
-```
-
-### 7️⃣ Maintainer: Review and Merge the Development Version PR
-
-**Checklist:**
-
-- ✅ Only version files updated to `+dev`
-- ✅ No unintended changes
-
-**Merge Strategy:**
-
-- Merge with commit message: `chore: development version vX.Y.Z+dev`
+See `.github/workflwows/bump-version.yml`for details.
 
 ## ✅ Quick Reference
 
 | Step | Actor | Action |
 | ---- | ----- | ------ |
-| **1. Prepare release branch** | Contributor | Bump version & changelog via Commitizen |
+| **1. Prepare release branch** | Contributor | Bump version & changelog |
 | **2. Open release PR** | Contributor | Submit release for review |
 | **3. Review & merge release PR** | Maintainer | Finalize changes into `main` |
-| **4. Publish GitHub Release** | Maintainer | Create tag & notify users |
-| **5. Prepare development version branch** | Maintainer | Set development marker |
-| **6. Open development PR** | Maintainer (or Contributor) | Propose returning to development state |
-| **7. Review & merge development PR** | Maintainer | Mark repository as back in development |
+| **4. Publish GitHub Release** | CI | Create tag & notify users |
+| **5. Prepare development version branch** | CI | Set development marker |