irr-github · Dec 11, 2025 · Dec 4, 2025 · Dec 5, 2025 · Dec 5, 2025 · Dec 5, 2025
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -60,13 +60,13 @@ jobs:
       - name: Determine deployment alias
         id: deployment
         run: |
-          if [ "${{ github.ref }}" = "refs/heads/main" ]; then
-            echo "ALIAS=dev" >> $GITHUB_OUTPUT
-            echo "TITLE=Development (main)" >> $GITHUB_OUTPUT
+          if [ "${{ github.ref }}" = "refs/heads/develop" ]; then
+            echo "ALIAS=latest" >> $GITHUB_OUTPUT
+            echo "TITLE=Development (latest)" >> $GITHUB_OUTPUT
             echo "SET_DEFAULT=true" >> $GITHUB_OUTPUT
-          elif [ "${{ github.ref }}" = "refs/heads/develop" ]; then
-            echo "ALIAS=develop" >> $GITHUB_OUTPUT
-            echo "TITLE=Development (develop)" >> $GITHUB_OUTPUT
+          elif [ "${{ github.ref }}" = "refs/heads/main" ]; then
+            echo "ALIAS=stable" >> $GITHUB_OUTPUT
+            echo "TITLE=Stable (main)" >> $GITHUB_OUTPUT
             echo "SET_DEFAULT=false" >> $GITHUB_OUTPUT
           elif [ "${{ github.ref }}" = "refs/heads/prepare_release" ]; then
             echo "ALIAS=test-release" >> $GITHUB_OUTPUT
@@ -86,9 +86,9 @@ jobs:
 
           # Deploy current version with appropriate alias
           if [ "${{ steps.deployment.outputs.SET_DEFAULT }}" = "true" ]; then
-            # For main branch: deploy as both alias and latest, then set latest as default 
-            mike deploy --push --update-aliases "$VERSION" latest -t "Version $VERSION"
-            mike set-default --push latest
+            # For develop branch: deploy with 'latest' alias and set as default
+            mike deploy --push --update-aliases "dev" "$ALIAS" -t "$TITLE"
+            mike set-default --push "$ALIAS"
           else
             # For other branches: just deploy with the alias
             mike deploy --push --update-aliases "$ALIAS" -t "$TITLE"

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -1,124 +1,124 @@
 name: Release
 
 on:
-    push:
-        tags:
-            - "v*.*.*"
-    workflow_dispatch:
-        inputs:
-            tag:
-                description: "Tag to release (e.g., v1.3.0)"
-                required: true
-                type: string
+  push:
+    tags:
+      - "v*.*.*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Tag to release (e.g., v1.3.0)"
+        required: true
+        type: string
 
 permissions:
-    contents: write
-    pages: write
-    id-token: write
+  contents: write
+  pages: write
+  id-token: write
 
 jobs:
-    create-release:
-        name: Create GitHub Release
-        runs-on: ubuntu-latest
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v4
-              with:
-                  fetch-depth: 0
+  create-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-            - name: Get version from tag
-              id: get_version
-              run: |
-                  if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    VERSION="${{ inputs.tag }}"
-                  else
-                    VERSION=${GITHUB_REF#refs/tags/}
-                  fi
-                  echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT
-                  echo "VERSION_NUMBER=${VERSION#v}" >> $GITHUB_OUTPUT
+      - name: Get version from tag
+        id: get_version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ inputs.tag }}"
+          else
+            VERSION=${GITHUB_REF#refs/tags/}
+          fi
+          echo "VERSION=${VERSION}" >> $GITHUB_OUTPUT
+          echo "VERSION_NUMBER=${VERSION#v}" >> $GITHUB_OUTPUT
 
-            - name: Extract changelog for this version
-              id: changelog
-              run: |
-                  VERSION="${{ steps.get_version.outputs.VERSION_NUMBER }}"
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          VERSION="${{ steps.get_version.outputs.VERSION_NUMBER }}"
 
-                  # Extract the changelog section for this version
-                  awk -v ver="## \\[$VERSION\\]" '
-                    $0 ~ ver {flag=1; next}
-                    /^## \[/ && flag {exit}
-                    flag && NF {print}
-                  ' CHANGELOG.md > release_notes.md
+          # Extract the changelog section for this version
+          awk -v ver="## \\[$VERSION\\]" '
+            $0 ~ ver {flag=1; next}
+            /^## \[/ && flag {exit}
+            flag && NF {print}
+          ' CHANGELOG.md > release_notes.md
 
-                  # If no specific notes found, use a default message
-                  if [ ! -s release_notes.md ]; then
-                    echo "Release $VERSION of PyPSA-China (PIK)" > release_notes.md
-                    echo "" >> release_notes.md
-                    echo "For detailed changes, see the [CHANGELOG](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)." >> release_notes.md
-                  fi
+          # If no specific notes found, use a default message
+          if [ ! -s release_notes.md ]; then
+            echo "Release $VERSION of PyPSA-China (PIK)" > release_notes.md
+            echo "" >> release_notes.md
+            echo "For detailed changes, see the [CHANGELOG](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md)." >> release_notes.md
+          fi
 
-            - name: Create Release
-              uses: softprops/action-gh-release@v1
-              with:
-                  tag_name: ${{ steps.get_version.outputs.VERSION }}
-                  name: PyPSA-China PIK ${{ steps.get_version.outputs.VERSION }}
-                  body_path: release_notes.md
-                  draft: false
-                  prerelease: false
-              env:
-                  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ steps.get_version.outputs.VERSION }}
+          name: PyPSA-China PIK ${{ steps.get_version.outputs.VERSION }}
+          body_path: release_notes.md
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
-    deploy-versioned-docs:
-        name: Deploy Versioned Documentation
-        runs-on: ubuntu-latest
-        needs: create-release
-        steps:
-            - name: Checkout code
-              uses: actions/checkout@v4
-              with:
-                  fetch-depth: 0
+  deploy-versioned-docs:
+    name: Deploy Versioned Documentation
+    runs-on: ubuntu-latest
+    needs: create-release
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
 
-            - name: Get version from tag
-              id: get_version
-              run: |
-                  if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-                    VERSION="${{ inputs.tag }}"
-                  else
-                    VERSION=${GITHUB_REF#refs/tags/}
-                  fi
-                  echo "VERSION=${VERSION#v}" >> $GITHUB_OUTPUT
+      - name: Get version from tag
+        id: get_version
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            VERSION="${{ inputs.tag }}"
+          else
+            VERSION=${GITHUB_REF#refs/tags/}
+          fi
+          echo "VERSION=${VERSION#v}" >> $GITHUB_OUTPUT
 
-            - name: Set up Python
-              uses: actions/setup-python@v5
-              with:
-                  python-version: "3.12"
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
 
-            - name: Configure Git
-              run: |
-                  git config --global user.name "github-actions[bot]"
-                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Configure Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
 
-            - name: Install dependencies
-              run: |
-                  python -m pip install --upgrade pip
-                  pip install mkdocs
-                  pip install mkdocs_gen_files
-                  pip install "mkdocstrings[python]"
-                  pip install mkdocs-awesome-nav
-                  pip install mkdocs-material
-                  pip install mkdocs-include-dir-to-nav
-                  pip install python-markdown-math
-                  pip install mike>=2.0.0
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs
+          pip install mkdocs_gen_files
+          pip install "mkdocstrings[python]"
+          pip install mkdocs-awesome-nav
+          pip install mkdocs-material
+          pip install mkdocs-include-dir-to-nav
+          pip install python-markdown-math
+          pip install mike>=2.0.0
 
-            - name: Deploy documentation with mike
-              run: |
-                  VERSION="${{ steps.get_version.outputs.VERSION }}"
-                  # Deploy this version and make it the latest
-                  mike deploy --push --update-aliases "$VERSION" latest
-                  # Set latest as the default version
-                  mike set-default --push latest
+      - name: Deploy documentation with mike
+        run: |
+          VERSION="${{ steps.get_version.outputs.VERSION }}"
+          # Deploy this version and make it stable
+          mike deploy --push --update-aliases "$VERSION" stable
+          # Set stable as the default version (releases take precedence over dev)
+          mike set-default --push stable
 
-            - name: Create documentation update message
-              run: |
-                  VERSION="${{ steps.get_version.outputs.VERSION }}"
-                  echo "📚 Documentation for version $VERSION has been deployed to GitHub Pages"
-                  echo "View at: https://pik-piam.github.io/PyPSA-China-PIK/"
+      - name: Create documentation update message
+        run: |
+          VERSION="${{ steps.get_version.outputs.VERSION }}"
+          echo "📚 Documentation for version $VERSION has been deployed to GitHub Pages"
+          echo "View at: https://pik-piam.github.io/PyPSA-China-PIK/"
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -104,35 +104,51 @@ pip install pytest pytest-cov black flake8
    git push origin feature/your-feature-name
    ```
 
-2. **Open a Pull Request** on GitHub
+2. **Open a Pull Request** on GitHub:
+   - **Target branch**: 
+     - Use `develop` for new features and non-critical bug fixes
+     - Use `main` only for hotfixes or critical patches to the current stable release
+   - Most contributions should target the `develop` branch
+
 3. **Fill out the PR template** completely
 4. **Link related issues** using keywords like "Closes #123"
 5. **Wait for review** and address any feedback
 6. **Ensure CI checks pass**
 
+### Branch Strategy
+
+- **develop**: Active development branch for new features and improvements
+  - Continuous integration and testing
+  - Documentation deployed as "latest" version
+  - Merged to `main` before releases
+
+- **main**: Stable branch reflecting the latest release
+  - Should always be in a releasable state
+  - Tagged with version numbers for releases
+  - Documentation deployed as "stable" version
+
+- **feature branches**: For individual features or bug fixes
+  - Created from and merged back to `develop`
+  - Named descriptively: `feature/description` or `fix/description`
+
 ## Coding Standards
 
 ### Python Code
 
 - Follow [PEP 8](https://pep8.org/) style guide
 - Use meaningful variable and function names
-- Add docstrings to functions and classes:
+- Add docstrings to functions and classes using Google style with type hints:
   ```python
   def my_function(param1: str, param2: int) -> bool:
       """
       Brief description of function.
 
-      Parameters
-      ----------
-      param1 : str
-          Description of param1
-      param2 : int
-          Description of param2
-
-      Returns
-      -------
-      bool
-          Description of return value
+      Args:
+          param1 (str): Description of param1
+          param2 (int): Description of param2
+
+      Returns:
+          bool: Description of return value
       """
       pass
   ```
@@ -248,6 +264,7 @@ Releases are managed by project maintainers:
 - Welcome newcomers and help them get started
 - Focus on constructive feedback
 - Maintain a professional environment
+- Questions are always welcome but please check the documentation first!
 
 ## Questions?
 

diff --git a/docs/release-guide.md b/docs/release-guide.md
@@ -107,8 +107,8 @@ Once the tag is pushed, the Release workflow automatically:
 2. **Deploys Versioned Documentation**:
    - Builds documentation with MkDocs
    - Deploys to GitHub Pages using mike
-   - Updates version aliases (vX.Y.Z and latest)
-   - Sets the new version as default
+   - Creates version vX.Y.Z with alias 'stable'
+   - Sets 'stable' as the default version (releases take precedence over development)
 
 ### 6. Verify the Release
 
@@ -219,11 +219,14 @@ mike set-default VERSION --push
 # Delete a version
 mike delete VERSION --push
 
-# Deploy without updating latest alias
+# Deploy without updating any alias
 mike deploy VERSION --push
 
-# Deploy and update latest alias
-mike deploy --update-aliases VERSION latest --push
+# Deploy release with stable alias (done by release workflow)
+mike deploy --update-aliases VERSION stable --push
+
+# Deploy development with latest alias (done by docs workflow on develop)
+mike deploy --update-aliases dev latest --push
 ```
 
 ### Local Testing

diff --git a/docs/releases.md b/docs/releases.md
@@ -10,8 +10,9 @@ The current stable release is **v1.3.2**. See the [CHANGELOG](https://github.com
 
 You can view documentation for different versions using the version selector in the navigation bar. Available versions:
 
-- **latest** - The most recent stable release (currently v1.3.2)
-- **dev** - Development version from the main branch
+- **stable** - The most recent stable release (points to latest version tag, e.g., v1.3.2)
+- **latest** - Latest development version from the develop branch
+- **vX.Y.Z** - Specific release versions (e.g., v1.3.2)
 
 ## Release Schedule