meteocat 2.2.7 → 3.0.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,7 +6,7 @@ labels: bug
 assignees: ""
 ---
 
-**IMPORTANT: Please search the issues, including closed issues before opening a new issue.  
+**IMPORTANT: Please search the issues (including closed ones) *and* check the [Wiki - Troubleshooting](https://github.com/figorr/meteocat/wiki/Troubleshooting) page before opening a new issue. 
 The template is mandatory; failure to use it will result in issue closure.**
 
 ---

package/.github/workflows/publish-zip.yml

@@ -9,46 +9,56 @@ jobs:
     runs-on: ubuntu-latest
     permissions:
       contents: write
+
     steps:
+      # Paso 1: Checkout del repositorio completo
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           ref: master
+          fetch-depth: 0
+
+      # Paso 2: Obtener la versión del release recién publicado
+      - name: Get release version
+        id: release-version
+        run: |
+          version="${GITHUB_REF#refs/tags/v}"
+          echo "Release version: $version"
+          echo "version=$version" >> $GITHUB_OUTPUT
 
+      # Paso 3: Actualizar hacs.json con la última versión de Home Assistant
       - name: Get latest Home Assistant version
         id: ha-version
         run: |
           latest=$(curl -s https://api.github.com/repos/home-assistant/core/releases/latest | jq -r .tag_name)
-          # quitamos prefijo "v" si existe
           latest_clean=${latest#v}
-          echo "Latest HA version: $latest_clean"
-          echo "version=$latest_clean" >> $GITHUB_OUTPUT
+          echo "ha_version=$latest_clean" >> $GITHUB_OUTPUT
 
       - name: Update hacs.json
         run: |
-          ha_version="${{ steps.ha-version.outputs.version }}"
-          echo "Updating hacs.json with HA version: $ha_version"
+          ha_version="${{ steps.ha-version.outputs.ha_version }}"
           jq --arg ver "$ha_version" '.homeassistant = $ver' hacs.json > tmp.json && mv tmp.json hacs.json
-          cat hacs.json
 
       - name: Commit updated hacs.json
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add hacs.json
-          if git commit -m "chore: update hacs.json with latest Home Assistant version"; then
+          if git commit -m "chore: update hacs.json with latest Home Assistant version [skip ci]"; then
             git push origin master
           else
             echo "No changes to commit"
           fi
 
+      # Paso 4: Crear zip de la integración con nombre fijo meteocat.zip
       - name: Zip integration
         run: |
           cd custom_components/meteocat
-          zip -r meteocat.zip ./
-          mv meteocat.zip $GITHUB_WORKSPACE/
+          zip -r "$GITHUB_WORKSPACE/meteocat.zip" ./
+          echo "Zip created at $GITHUB_WORKSPACE/meteocat.zip"
 
+      # Paso 5: Subir meteocat.zip al release de GitHub
       - name: Upload meteocat.zip to release
         uses: softprops/action-gh-release@v2.2.1
         with:

package/.github/workflows/release.yml

@@ -11,27 +11,29 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      # Paso 1: Configurar el repositorio
+      # Paso 1: Checkout completo (necesario para semantic-release y tags)
       - name: Checkout repository
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
 
-      # Paso 2: Configurar Node.js (requerido para semantic-release)
+      # Paso 2: Configurar Node.js
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: 20.8.1 # Versión compatible con semantic-release
+          node-version: 20.8.1
 
-      # Paso 3: Instalar dependencias necesarias
+      # Paso 3: Instalar dependencias
       - name: Install dependencies
         run: npm ci
-      
+
       # Paso 4: Configurar el autor de Git
       - name: Configure Git author
         run: |
           git config user.name "semantic-release-bot"
           git config user.email "jdcuartero@yahoo.es"
 
-      # Paso 5: Ejecutar semantic-release
+      # Paso 5: Ejecutar semantic-release (se encargará de actualizar versiones, changelog, y release)
       - name: Run semantic-release
         env:
           GITHUB_TOKEN: ${{ secrets.WORKFLOW_TOKEN }}

package/.github/workflows/stale.yml

@@ -56,8 +56,8 @@ jobs:
           repo-token: ${{ secrets.GITHUB_TOKEN }}
           only-labels: "logs required"
           days-before-stale: 7
-          days-before-close: 7
+          days-before-close: 1
           stale-issue-message: >-
             This issue has been marked as *requiring logs*, but no activity has been detected for 7 days.
-            Since logs were not provided, this issue will now be closed.
+            Since logs were not provided, this issue will now be closed in 1 day.
           stale-issue-label: "stale"

package/.github/workflows/sync-gitlab.yml

@@ -0,0 +1,96 @@
+name: Sync to GitLab
+
+on:
+  release:
+    types: [published]  # Se dispara al publicarse un release en GitHub
+  workflow_dispatch:    # Permite ejecución manual desde la interfaz
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+
+    steps:
+      # Paso 1: Checkout completo
+      - name: Checkout repository
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      # Paso 2: Configurar Git
+      - name: Configure Git
+        run: |
+          git config user.name "github-bot"
+          git config user.email "bot@github.com"
+
+      # Paso 3: Añadir remoto de GitLab
+      - name: Add GitLab remote
+        env:
+          GL_REMOTE_URL: ${{ secrets.GL_REMOTE_URL }}
+          GL_TOKEN: ${{ secrets.GL_TOKEN }}
+        run: |
+          git remote add gitlab "https://oauth2:${GL_TOKEN}@${GL_REMOTE_URL#https://}"
+
+      # Paso 4: Comprobar divergencias en master
+      - name: Check for diverging commits
+        run: |
+          git fetch gitlab master
+          if ! git merge-base --is-ancestor gitlab/master master; then
+            echo "❌ GitLab master tiene commits que GitHub no tiene. Revisar antes de sincronizar."
+            exit 1
+          fi
+
+      # Paso 5: Push de commits y tags a GitLab
+      - name: Push commits and tags to GitLab
+        run: |
+          git push gitlab master
+          git push gitlab --tags
+
+      # Paso 6: Crear release en GitLab si no existe
+      - name: Create GitLab release
+        env:
+          GL_REMOTE_URL: ${{ secrets.GL_REMOTE_URL }}
+          GL_TOKEN: ${{ secrets.GL_TOKEN }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          PROJECT_PATH=$(echo $GL_REMOTE_URL | sed -E 's#https://[^/]+/(.*)\.git#\1#')
+          PROJECT_PATH_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('''$PROJECT_PATH''', safe=''))")
+
+          EXISTING=$(curl -s --header "PRIVATE-TOKEN: $GL_TOKEN" "https://gitlab.com/api/v4/projects/$PROJECT_PATH_ENCODED/releases/$RELEASE_TAG")
+
+          if echo "$EXISTING" | grep -q 'tag_name'; then
+            echo "Release ya existe en GitLab: $RELEASE_TAG"
+          else
+            echo "Creando release en GitLab: $RELEASE_TAG"
+            curl -s --request POST "https://gitlab.com/api/v4/projects/$PROJECT_PATH_ENCODED/releases" \
+              --header "PRIVATE-TOKEN: $GL_TOKEN" \
+              --header "Content-Type: application/json" \
+              --data "{
+                \"name\": \"Release $RELEASE_TAG\",
+                \"tag_name\": \"$RELEASE_TAG\",
+                \"description\": \"Release sincronizado desde GitHub\"
+              }"
+          fi
+
+      # Paso 7: Subir meteocat.zip como asset al release de GitLab
+      - name: Upload meteocat.zip to GitLab release
+        env:
+          GL_REMOTE_URL: ${{ secrets.GL_REMOTE_URL }}
+          GL_TOKEN: ${{ secrets.GL_TOKEN }}
+          RELEASE_TAG: ${{ github.ref_name }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          PROJECT_PATH=$(echo $GL_REMOTE_URL | sed -E 's#https://[^/]+/(.*)\.git#\1#')
+          PROJECT_PATH_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('''$PROJECT_PATH''', safe=''))")
+
+          ASSET_NAME="meteocat.zip"
+          ZIP_URL="https://github.com/${GITHUB_REPOSITORY}/releases/download/$RELEASE_TAG/meteocat.zip"
+
+          echo "Subiendo $ASSET_NAME al release de GitLab desde $ZIP_URL"
+          curl --request POST "https://gitlab.com/api/v4/projects/$PROJECT_PATH_ENCODED/releases/$RELEASE_TAG/assets/links" \
+            --header "PRIVATE-TOKEN: $GL_TOKEN" \
+            --header "Content-Type: application/json" \
+            --data "{
+              \"name\": \"$ASSET_NAME\",
+              \"url\": \"$ZIP_URL\"
+            }"
+

package/.releaserc

@@ -9,15 +9,29 @@
         "changelogFile": "CHANGELOG.md"
       }
     ],
-    "@semantic-release/npm",
-    "@semantic-release/github",
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "bash ./scripts/update_version.sh ${nextRelease.version}"
+      }
+    ],
     [
       "@semantic-release/git",
       {
-        "assets": ["CHANGELOG.md", "package.json", "pyproject.toml"],
-        "message": "v${nextRelease.version}\n\n${nextRelease.notes}"
+        "assets": [
+          "pyproject.toml",
+          "custom_components/meteocat/manifest.json",
+          "custom_components/meteocat/version.py",
+          "custom_components/meteocat/__init__.py",
+          "CHANGELOG.md",
+          "package.json",
+          "package-lock.json"
+        ],
+        "message": "chore(release): v${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
       }
-    ]
+    ],
+    "@semantic-release/npm",
+    "@semantic-release/github"
   ],
   "repositoryUrl": "https://github.com/figorr/meteocat"
 }

package/AUTHORS.md

@@ -10,3 +10,4 @@
 
 ## Contributors
 
+- mcasellas [GitHub](https://github.com/mcasellas)

package/CHANGELOG.md

@@ -1,3 +1,42 @@
+# [3.0.0](https://github.com/figorr/meteocat/compare/v2.3.0...v3.0.0) (2025-09-14)
+
+
+### Features
+
+* change unique_id to use town_id ([3a048ce](https://github.com/figorr/meteocat/commit/3a048ce48a0e1f3ee7642c28bbe7ac6e6e3fc298))
+
+
+### BREAKING CHANGES
+
+* Entities now use town_id instead of region_id in their unique_id.
+This change enables multiple integration entries that share the same region_id but different towns.
+
+Recommended upgrade path:
+1. Uninstall the existing integration (v2.x).
+2. Restart Home Assistant.
+3. Install v3.0.0 and reconfigure the integration.
+
+If you update directly without uninstalling first, old entities will remain as 'unavailable' and new entities will be created (possibly with a suffix like '2').
+In that case, you may need to manually remove the old entities and update your automations or dashboards.
+
+## [2.3.0](https://github.com/figorr/meteocat/compare/v2.2.7...v2.3.0) (2025-09-10)
+
+
+### Features
+
+* download and save town and station json files during setup ([7b98c22](https://github.com/figorr/meteocat/commit/7b98c22d5ca43d4cbf80895e11c02594208f7470))
+* include options documentation ([a85ef74](https://github.com/figorr/meteocat/commit/a85ef7492eb8ed4af99b8d0f50b8e77ff7f7976a))
+* include options image ([dbb047a](https://github.com/figorr/meteocat/commit/dbb047a6bdf32af03fec8351c9a608593b369e3b))
+* include regenerate assets files option ([f2ce357](https://github.com/figorr/meteocat/commit/f2ce357c8ce6371d97523870f4bf6a9cba6a151c))
+* recover assets files ([f493b33](https://github.com/figorr/meteocat/commit/f493b33e54e10994b6b08232f37dd5bb35f4a9b7))
+* regenerate assets option translation ([317ce9f](https://github.com/figorr/meteocat/commit/317ce9fecc03f88b8b8072b41b357846fb075dcc))
+* safe remove keeping common entry files ([6cefe04](https://github.com/figorr/meteocat/commit/6cefe04289b1b74fe30d615e7056bd643d845b89))
+* **storage:** moving the API downloaded files to the new folder meteocat_files ([06c68e3](https://github.com/figorr/meteocat/commit/06c68e36b5669efc8fe3174a71e41624e9728b07))
+* update .gitignore ([fac7772](https://github.com/figorr/meteocat/commit/fac7772a1093f2165e1b33098631096138617a6d))
+* update README ([9855939](https://github.com/figorr/meteocat/commit/98559398e6bae30e8e9c9ff2b2fe27409a3930bd))
+* update repo files structure ([0778679](https://github.com/figorr/meteocat/commit/0778679d218a89e89bb18791f1245c5c9f7b188f))
+
+
 ## [2.2.7](https://github.com/figorr/meteocat/compare/v2.2.6...v2.2.7) (2025-08-29)
 
 

package/README.md

@@ -2,8 +2,13 @@
 ![Meteocat Banner](images/banner.png)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 [![Python version compatibility](https://img.shields.io/pypi/pyversions/meteocat)](https://pypi.org/project/meteocat)
-[![pipeline status](https://gitlab.com/figorr/meteocat/badges/master/pipeline.svg)](https://gitlab.com/figorr/meteocat/commits/master)
-
+[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/hacs/integration)
+[![Validate](https://github.com/figorr/meteocat/actions/workflows/validate.yaml/badge.svg)](https://github.com/figorr/meteocat/actions/workflows/validate.yaml)
+[![Release](https://github.com/figorr/meteocat/actions/workflows/release.yml/badge.svg)](https://github.com/figorr/meteocat/actions/workflows/release.yml)
+![GitHub all releases](https://img.shields.io/github/downloads/figorr/meteocat/total)
+![GitHub release](https://img.shields.io/github/downloads/figorr/meteocat/latest/total)
+![Latest release](https://img.shields.io/github/v/release/figorr/meteocat?label=latest)
+[![Breaking Changes](https://img.shields.io/badge/Breaking%20Changes-critical?logo=data:image/svg+xml;base64,PHN2ZyBpZD0iTGF5ZXJfMSIgZGF0YS1uYW1lPSJMYXllciAxIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjIuODggMTExLjU0Ij48ZGVmcz48c3R5bGU+LmNscy0xe2ZpbGw6IzFhMWExYTt9LmNscy0ye2ZpbGw6I2ZmZWYxMTtmaWxsLXJ1bGU6ZXZlbm9kZDt9PC9zdHlsZT48L2RlZnM+PHRpdGxlPmNhdXRpb248L3RpdGxlPjxwYXRoIGNsYXNzPSJjbHMtMSIgZD0iTTIuMzUsODQuNDIsNDUuMjgsMTAuMmwuMTctLjI3aDBBMjMsMjMsMCwwLDEsNTIuNSwyLjY5LDE3LDE3LDAsMCwxLDYxLjU3LDBhMTYuNywxNi43LDAsMCwxLDkuMTEsMi42OSwyMi43OSwyMi43OSwwLDAsMSw3LDcuMjZxLjE5LjMyLjM2LjYzbDQyLjIzLDczLjM0LjI0LjQ0aDBhMjIuNDgsMjIuNDgsMCwwLDEsMi4zNywxMC4xOSwxNy42MywxNy42MywwLDAsMS0yLjE3LDguMzUsMTUuOTQsMTUuOTQsMCwwLDEtNi45Myw2LjZjLS4xOS4xLS4zOS4xOC0uNTguMjZhMjEuMTksMjEuMTksMCwwLDEtOS4xMSwxLjc1djBIMTcuNjFjLS4yMiwwLS40NCwwLS42NSwwYTE4LjA3LDE4LjA3LDAsMCwxLTYuMi0xLjE1QTE2LjQyLDE2LjQyLDAsMCwxLDMsMTA0LjI0YTE3LjUzLDE3LjUzLDAsMCwxLTMtOS41NywyMywyMywwLDAsMSwxLjU3LTguNzQsNy42Niw3LjY2LDAsMCwxLC43Ny0xLjUxWiIvPjxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTksODguNzUsNTIuMTIsMTQuMTZjNS4yNC04LjI1LDEzLjU0LTguNDYsMTguODcsMGw0Mi40Myw3My42OWMzLjM5LDYuODEsMS43MSwxNi05LjMzLDE1Ljc3SDE3LjYxQzEwLjM1LDEwMy44LDUuNjcsOTcuNDMsOSw4OC43NVoiLz48cGF0aCBjbGFzcz0iY2xzLTEiIGQ9Ik01Ny41Nyw4Mi42OUE1LjQ4LDUuNDgsMCwwLDEsNjEsODEuMTFhNS42Niw1LjY2LDAsMCwxLDQuNDIsMS42Niw1LjUzLDUuNTMsMCwwLDEsMS42MiwzLjU0QTUuNiw1LjYsMCwwLDEsNjcsODcuNzJhNiw2LDAsMCwxLS40MiwxLjM0LDUuNTMsNS41MywwLDAsMS0yLjkyLDIuODQsNS43OSw1Ljc5LDAsMCwxLTQuNTctLjEsNS41MSw1LjUxLDAsMCwxLTIuODEtMi45NCw1LjMxLDUuMzEsMCwwLDEtLjM2LTEuMjcsNS45LDUuOSwwLDAsMS0uMDYtMS4zMmgwYTYuNDUsNi40NSwwLDAsMSwuNTctMiw0LjYsNC42LDAsMCwxLDEuMTQtMS41NlptOC4xNS0xMC4yNGMtLjE5LDQuNzktOC4zMSw0LjgtOC40OSwwLS44Mi04LjIxLTIuOTItMjcuNy0yLjg2LTM1LjQyLjA3LTIuMzgsMi0zLjc4LDQuNTYtNC4zMmExMS4xOSwxMS4xOSwwLDAsMSwyLjQ5LS4yNCwxMS43NywxMS43NywwLDAsMSwyLjUuMjVjMi42MS41NSw0LjY1LDIsNC42NSw0LjQ0di4yNEw2NS43Miw3Mi40NVoiLz48L3N2Zz4=&logoColor=white)](#-breaking-changes---upgrade-to-3x)
 
 This is a project to obtain meteorological data from the Meteocat API inside the Home Assistant environment.
 
@@ -17,8 +22,39 @@ Commercial use of this project or the data obtained from the API is not allowed
 
 This is a personal project.
 
-Authors:
-- Figorr
+**Authors:**  
+- [Figorr](https://github.com/figorr)
+
+**Contributors:**  
+- [mcasellas](https://github.com/mcasellas) – contributed [c505f27](https://github.com/figorr/meteocat/commit/c505f27)
+
+## ⚠️ Breaking changes - Upgrade to 3.0.0 or later coming from prior versions
+
+Version **3.0.0 and later** introduces a **breaking change** in how entities are identified.
+
+### ⚠️ What this affects
+- This affects any update **from a version prior to 3.0.0** to **any version 3.x or later**. 
+- Entities now use **`town_id`** instead of `region_id` in their `unique_id`.  
+- This change allows multiple integration entries that share the same `region_id` but different towns.  
+
+### ✅ Recommended upgrade procedure
+To avoid issues with duplicated or unavailable entities:
+
+1. **Uninstall** the existing integration (v2.x).  
+2. **Restart** Home Assistant.  
+3. **Install v3.0.0 or later** and configure the integration again.  
+
+### 🚨 If you update directly
+If you update without uninstalling first:
+
+- Old entities will remain as **Unavailable**.  
+- New entities will be created (sometimes with a suffix like `2`).  
+- You may need to manually **remove old entities** and update your automations, dashboards, or scripts to point to the new entities.
+
+### 📑 Additional notes
+
+- This change affects all entity types, including **sensors, diagnostic sensors, and alerts**.  
+- Always backup your **Home Assistant configuration** before performing major upgrades.
 
 ## Installation
 
@@ -31,7 +67,6 @@ Authors:
 1. Click `+ Add Integration`
 1. Search for `Meteocat` and follow the configuration instructions
 
-
 #### HACS - Install from the store
 1. Go to `HACS`
 1. Search for `Meteocat` and add it to HACS
@@ -80,11 +115,67 @@ To change units select one of the entities and open the more info dialog and cli
 
 ![Entity more info settings dialog](images/change_units.png)
 
+## Options
+
+Once the integration is installed, you can reconfigure some parameters without having to remove and reinstall Meteocat.
+
+Go to:
+`Settings > Devices & Services > Meteocat > Configure`
+
+You will see three available options:
+
+- **Update API Key and limits**  
+  Allows you to change the API Key and update all API plan limits at the same time.
+
+- **Update limits only**  
+  Allows you to adjust only the API plan limits, keeping the same API Key.
+
+- **Regenerate assets**  
+  If for any reason some files in the `assets` folder (`towns.json`, `stations.json`, `variables.json`, `symbols.json`, or `stations_<town_id>.json`) are missing or outdated, you can regenerate them directly from the options menu.  
+  > ℹ️ If the Meteocat API is not available at that moment, the integration will still start, and you can retry regeneration later.
+
+### Accessing the Options Menu
+
+You can access the Options Menu in two ways, both inside the integration:
+
+- **Setup Options**  
+
+  ![Setup Options menu](images/setup_options.png)
+
+- **System Options**  
+
+  ![System Options menu](images/system_options.png)
+
+Once inside, you will see the following options:  
+
+![Available Options](images/options.png)
+
+
+## Uninstallation
+
+To correctly uninstall the integration:
+
+- If you are upgrading due to **breaking changes**, remove all configured entries from  
+  **Settings > Devices & Services > Integrations**, restart Home Assistant, and reinstall the new version.  
+- If you want to **completely remove Meteocat**, after removing the entries and restarting, also uninstall the integration from **HACS > Integrations**.
+
+👉 For detailed steps with screenshots, check the [Uninstallation Guide](https://github.com/figorr/meteocat/wiki/Uninstallation).
+
+# Documentation
+
+For more detailed information about:
+- Installation and configuration  
+- Usage examples  
+- Extra attributes in sensors  
+- Known issues and troubleshooting  
+
+please visit the [📖 Meteocat Wiki](https://github.com/figorr/meteocat/wiki).
+
 # Contributing
 
-1.  [Check for open features/bugs](https://gitlab.com/figorr/meteocat/issues)
-    or [initiate a discussion on one](https://gitlab.com/figorr/meteocat/issues/new).
-2.  [Fork the repository](https://gitlab.com/figorr/meteocat/forks/new).
+1.  [Check for open features/bugs](https://github.com/figorr/meteocat/issues)
+    or [initiate a discussion on one](https://github.com/figorr/meteocat/issues/new/choose).
+2.  [Fork the repository](https://github.com/figorr/meteocat/fork).
 3.  Install the dev environment: `make init`.
 4.  Enter the virtual environment: `pipenv shell`
 5.  Code your new feature or bug fix.