From aa716c87a5a7524de8918f80c11a8efb3d751709 Mon Sep 17 00:00:00 2001 From: irr-github Date: Fri, 5 Dec 2025 10:02:04 +0100 Subject: [PATCH 1/2] fix mike aliases, add coverage report --- .github/workflows/docs.yml | 18 +-- .github/workflows/release.yml | 210 +++++++++++++++++----------------- 2 files changed, 114 insertions(+), 114 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index afde8b54..bac8cf63 100644 --- 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 index 736be1e2..81ceba59 100644 --- 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/" From 52618891d76ab3eb89cf7ae4107a167bfab23830 Mon Sep 17 00:00:00 2001 From: irr-github Date: Fri, 5 Dec 2025 10:19:39 +0100 Subject: [PATCH 2/2] update contribution guide --- CONTRIBUTING.md | 43 ++++++++++++++++++++++++++++++------------- docs/release-guide.md | 13 ++++++++----- docs/releases.md | 5 +++-- 3 files changed, 41 insertions(+), 20 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1e453650..5a5018bd 100644 --- 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 index d7b46643..b9efb26d 100644 --- 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 index 6a695cee..b6d01347 100644 --- 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