Update template

.github/workflows/bump_version.yaml

@@ -4,30 +4,47 @@ on:
   push:
     branches:
       - master
+      - main
   workflow_dispatch:
+    inputs:
+      increment:
+        description: 'Version increment (major, minor, patch)'
+        required: false
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+        default: patch
+
+permissions:
+  contents: write  # 用于创建和推送标签
+  pull-requests: write  # 用于创建 PR
 
 jobs:
   bump-version:
     if: "!startsWith(github.event.head_commit.message, 'bump:')"
     runs-on: ubuntu-latest
     name: "Bump version and create changelog with commitizen"
     steps:
-      - name: Load secret
-        uses: 1password/load-secrets-action@v2
-        with:
-          export-env: true
-        env:
-          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
-          PERSONAL_ACCESS_TOKEN: op://shawndengdev/github_access_token/credential
-
       - name: Check out
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: '${{ env.PERSONAL_ACCESS_TOKEN }}'
+          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
 
-      - name: Create bump and changelog
+      - id: cz
+        name: Create bump and changelog
         uses: commitizen-tools/commitizen-action@master
         with:
-          github_token: ${{ env.PERSONAL_ACCESS_TOKEN }}
-          branch: master
+          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+          changelog_increment_filename: body.md
+          increment: ${{ github.event.inputs.increment }}
+
+      - name: Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body_path: body.md
+          tag_name: ${{ env.REVISION }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

.github/workflows/deploy_docs.yaml

@@ -0,0 +1,28 @@
+name: Deploy Docs
+
+on:
+  push:
+    tags:
+      - '*'  # 匹配所有标签
+  workflow_dispatch:  # 保留手动触发选项
+
+permissions:
+  contents: write  # 用于部署到 GitHub Pages
+
+jobs:
+  setup:
+    uses: ./.github/workflows/setup.yaml
+    with:
+      install-deps: docs
+    secrets:
+      OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+
+  deploy:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Build and deploy documentation
+        run: uvx mkdocs gh-deploy --force
+        env:
+          GITHUB_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

.github/workflows/lint.yaml

@@ -1,39 +1,92 @@
 name: lint_and_unittest
 
-on: [ push, pull_request ]
+on: 
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: write  # 用于在 PR 中添加评论
 
 jobs:
-  lint_and_unittest:
+  setup:
+    uses: ./.github/workflows/setup.yaml
+    with:
+      install-deps: dev
+      python-version: "3.12"  # 使用最新版本
+    secrets:
+      OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+
+  lint:
+    needs: setup
     runs-on: ubuntu-latest
     steps:
-      - name: Load secret
-        uses: 1password/load-secrets-action@v2
-        with:
-          export-env: true
-        env:
-          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
-          PERSONAL_ACCESS_TOKEN: op://shawndengdev/github_access_token/credential
+      - name: Check Python version
+        run: python --version
 
-      - name: Check out
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: '${{ env.PERSONAL_ACCESS_TOKEN }}'
+      - name: Run lint checks
+        id: lint
+        run: uvx nox -s lint
+        continue-on-error: true
 
-      - uses: actions/setup-python@v5
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' && steps.lint.outcome == 'failure'
+        uses: actions/github-script@v7
         with:
-          python-version: "3.12"
+          script: |
+            const output = `#### 🔍 Lint Check Failed
+            Please fix the linting issues before merging.
+            You can run \`nox -s lint\` locally to check and fix issues.`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: output
+            })
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
-        with:
-          version: ">=0.4.0"
+      - name: Check lint result
+        if: steps.lint.outcome == 'failure'
+        run: exit 1
 
-      - name: Install dependencies
-        run: uv sync --extra dev
+  test-all:
+    needs: setup
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run tests on all Python versions
+        id: test
+        run: uvx nox -s test_all
+        continue-on-error: true
 
-      - name: Run lint checks
-        run: uvx nox -s lint
+      - name: Upload coverage reports
+        if: success()
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          flags: unittests
+
+      - name: Comment on PR
+        if: github.event_name == 'pull_request' && steps.test.outcome == 'failure'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const output = `#### ❌ Tests Failed
+            Please fix the test failures before merging.
+            You can run \`nox -s test_all\` locally to debug the failures.`;
+
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: output
+            })
 
-      - name: Run tests
-        run: uvx nox -s test
+      - name: Check test result
+        if: steps.test.outcome == 'failure'
+        run: exit 1

.github/workflows/release_build.yaml

@@ -1,56 +1,52 @@
-name: release-build
+name: release_build
+
 on:
-  workflow_dispatch:
   push:
     tags:
-      - '*.*.*'
+      - '*'  # 匹配所有标签
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version to release (e.g. 1.0.0)'
+        required: true
+        type: string
+
+permissions:
+  contents: write  # 用于创建 release
+  id-token: write  # 用于发布到 PyPI
 
 jobs:
-  release-build:
+  setup:
+    uses: ./.github/workflows/setup.yaml
+    with:
+      install-deps: dev
+      python-version: "3.12"
+    secrets:
+      OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+      PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+
+  build:
+    needs: setup
     runs-on: ubuntu-latest
-    permissions:
-      contents: write  # 用于创建 GitHub Release
     steps:
-      - uses: actions/checkout@v4
+      - name: Run tests
+        run: uvx nox -s test_all
 
-      - name: Load secret
-        uses: 1password/load-secrets-action@v2
-        with:
-          export-env: true
-        env:
-          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
-          PERSONAL_ACCESS_TOKEN: op://shawndengdev/github_access_token/credential
-          PYPI_TOKEN: op://shawndengdev/pypi_token/credential
-
-      - uses: actions/setup-python@v5
-        with:
-          python-version: "3.12"
+      - name: Build package
+        run: uvx nox -s build
 
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
+      - name: Create Release
+        id: create_release
+        uses: softprops/action-gh-release@v2
         with:
-          version: ">=0.4.0"
-
-      - name: Install dependencies
-        run: uv sync --extra dev
-
-      - name: Build and test
-        run: |
-          uvx nox -s lint
-          uvx nox -s test
-          uvx nox -s build
+          tag_name: ${{ github.event.inputs.version || github.ref_name }}
+          draft: false
+          prerelease: false
+          files: |
+            dist/*
 
       - name: Publish to PyPI
-        env:
-          UV_PUBLISH_TOKEN: ${{ env.PYPI_TOKEN }}
-        run: uv publish
-
-      - name: Release
-        uses: softprops/action-gh-release@v2
+        uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          files: |
-            dist/*.tar.gz
-            dist/*.whl
-          generate_release_notes: true
-        env:
-          GITHUB_TOKEN: ${{ env.PERSONAL_ACCESS_TOKEN }}
+          packages-dir: dist/
+          repository-url: https://upload.pypi.org/legacy/

.github/workflows/setup.yaml

@@ -0,0 +1,75 @@
+name: Reusable Setup
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        required: false
+        type: string
+        default: "3.12"
+      install-deps:
+        required: false
+        type: string
+        default: "dev"  # dev, docs, or none
+    secrets:
+      OP_SERVICE_ACCOUNT_TOKEN:
+        required: false
+      PERSONAL_ACCESS_TOKEN:
+        required: false
+    outputs:
+      python-version:
+        description: "The Python version that was set up"
+        value: ${{ jobs.setup.outputs.python-version }}
+
+jobs:
+  setup:
+    runs-on: ubuntu-latest
+    outputs:
+      python-version: ${{ steps.setup-python.outputs.python-version }}
+    steps:
+      - name: Load secret
+        if: ${{ inputs.install-deps != 'none' }}
+        uses: 1password/load-secrets-action@v2
+        with:
+          export-env: true
+        env:
+          OP_SERVICE_ACCOUNT_TOKEN: ${{ secrets.OP_SERVICE_ACCOUNT_TOKEN }}
+          PERSONAL_ACCESS_TOKEN: op://shawndengdev/github_access_token/credential
+
+      - name: Check out
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ env.PERSONAL_ACCESS_TOKEN || github.token }}
+
+      - name: Setup Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ inputs.python-version }}
+          cache: 'pip'
+          cache-dependency-path: |
+            **/requirements*.txt
+            **/pyproject.toml
+            **/poetry.lock
+            **/Pipfile.lock
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: ">=0.4.0"
+
+      - name: Get uv cache dir
+        id: get-uv-cache
+        run: echo "UV_CACHE_DIR=$(uv cache dir)" >> $GITHUB_OUTPUT
+
+      - name: Cache uv packages
+        uses: actions/cache@v4
+        with:
+          path: ${{ steps.get-uv-cache.outputs.UV_CACHE_DIR }}
+          key: ${{ runner.os }}-uv-${{ hashFiles('**/pyproject.toml', '**/requirements*.txt') }}
+          restore-keys: |
+            ${{ runner.os }}-uv-
+
+      - name: Install dependencies
+        if: ${{ inputs.install-deps != 'none' }}
+        run: uv sync --extra ${{ inputs.install-deps }}

.gitignore

@@ -7,4 +7,7 @@
 /.zip/
 /venv/
 /dist/
-/__pycache__/
+**/__pycache__/
+*.pyc
+# MkDocs build output
+/site/