feat: complete project initialization

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,41 @@
+---
+name: Bug report 🐛
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+## Describe the bug
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+## Expected behavior
+
+A clear and concise description of what you expected to happen.
+
+## Configuration
+
+```shell
+# use `pip freeze` to list all deps
+pip freeze
+```
+
+- Python version:
+- OS version:
+- deps version:
+- ...
+
+## Additional context
+
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,4 @@
+contact_links:
+  - name: I have a question 🤔
+    url: https://github.com/WSH032/pyproject-template/discussions # EDIT
+    about: If you have any question that's not clearly a bug, please open a discussion first.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request 💡
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+## Have you discussed it?
+
+- [ ] I have discussed this feature request in discussions, and developers ask me directly to create an issue here.
+
+## Describe your feature request
+
+A clear and concise description of what the feature is.
+
+## Is your feature request related to a problem? Please describe
+
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+## Describe the solution you'd like
+
+A clear and concise description of what you want to happen.
+
+## Describe alternatives you've considered
+
+A clear and concise description of any alternative solutions or features you've considered.
+
+## Additional context
+
+Add any other context or screenshots about the feature request here.

.github/actions/setup-envs/action.yml

@@ -0,0 +1,95 @@
+# WARNING: Do not change the name of this folder, keep `setup-envs`.
+# other workflows need the name of the action to work.
+
+# https://docs.github.com/actions/using-workflows/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache
+
+name: "Setup deps envs"
+description: |
+  Setup and cache deps envs for hatch and pre-commit.
+  will:
+      `pip install -r requirements.txt -U`
+      cache hatch venv
+      cache pre-commit venv
+  NOTE: `setup-python` first.
+
+inputs:
+  python-version:
+    description: "steps.setup-python.outputs.python-version"
+    required: true
+  python-path:
+    description: "steps.setup-python.outputs.python-path"
+    required: true
+  cache:
+    description: "Whether to use cache; set `true` to use cache"
+    default: "false"
+    required: false
+
+outputs:
+  hatch-cache-hit:
+    description: "hatch venv cache hit"
+    value: ${{ steps.cache-hatch-venv.outputs.cache-hit }}
+  pre-commit-cache-hit:
+    description: "pre-commit venv cache hit"
+    value: ${{ steps.cache-pre-commit-venv.outputs.cache-hit }}
+
+runs:
+  using: composite
+  steps:
+    # pip install hatch and pre-commit
+    - name: Install dependencies
+      shell: bash
+      run: |
+        python -m pip install --upgrade pip
+        python -m pip install -r requirements.txt -U
+        python -m pip freeze --local
+
+    # cache hatch venv
+    - name: cache hatch venv
+      id: cache-hatch-venv
+      if: ${{ inputs.cache == 'true' }}
+      uses: actions/cache@v3
+      env:
+        CACHE_VERSION: v1
+      with:
+        # Don't cache `.venv-default`, re-creat it instead.
+        # Because we can't use `==` to constraint the version of deps,
+        # resulting in cache not being up-to-date
+        path: |
+          ./.venv-docs
+          ./.venv-fmt
+        key:
+          # `v1` is the version of this cache key
+          "\
+          hatch-venv-\
+          ${{ runner.os }}-\
+          ${{ env.CACHE_VERSION }}-\
+          python${{ inputs.python-version }}-\
+          ${{ inputs.python-path }}-\
+          ${{ hashFiles('pyproject.toml', 'requirements.txt') }}\
+          "
+        restore-keys:
+          hatch-venv-${{ runner.os }}-
+
+    # cache pre-commit venv
+    # ref: https://github.com/pre-commit/action/blob/c7d159c2092cbfaab7352e2d8211ab536aa2267c/action.yml
+    #      https://pre-commit.com/#github-actions-example
+    - name: cache pre-commit venv
+      uses: actions/cache@v3
+      id: cache-pre-commit-venv
+      if: ${{ inputs.cache == 'true' }}
+      env:
+        CACHE_VERSION: v1
+      with:
+        path: ~/.cache/pre-commit
+        key:
+          # `v1` is the version of this cache key
+          "\
+          pre-commit-3-\
+          ${{ runner.os }}-\
+          ${{ env.CACHE_VERSION }}-\
+          python${{ inputs.python-version }}-\
+          ${{ inputs.python-path }}-\
+          ${{ hashFiles('.pre-commit-config.yaml') }}\
+          "
+        restore-keys:
+          pre-commit-3-${{ runner.os }}-

.github/dependabot.yml

@@ -0,0 +1,29 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  # GitHub Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    # https://docs.github.com/zh/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups
+    groups:
+      actions:
+        patterns:
+          - "*"
+  # Python
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "daily"
+    # groups:
+    #   pip:
+    #     patterns:
+    #       - "*"
+    #     update-types:
+    #       - "minor"
+    #       - "patch"

.github/pull_request_template.md

@@ -0,0 +1,13 @@
+<!-- Thanks for contributing 💚
+Given this is a project maintained by volunteers, please read this template to not waste your time, or ours! 😁 -->
+
+# Summary
+
+<!-- Write a small summary about what is happening here. -->
+
+# Checklist
+
+- [ ] I've read `CONTRIBUTING.md`.
+- [ ] I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
+- [ ] I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
+- [ ] I've updated the documentation accordingly.

.github/workflows/docs.yml

@@ -0,0 +1,71 @@
+# copy from: https://github.com/frankie567/httpx-ws/blob/main/.github/workflows/docs.yml
+
+# WARNING: Do not change the name of this file, keep `docs.yml`.
+# markdown badges are hard-coded to point to this file.
+
+name: Deploy documentation
+
+# Since document updates may be frequent,
+# we do not run tests when deploying documents,
+# instead test during the PR stage.
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+# Default to bash
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        # https://github.com/timvink/mkdocs-git-revision-date-localized-plugin#note-when-using-build-environments
+        with:
+          fetch-depth: 0
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        id: setup-python
+        with:
+          python-version: "3.10"
+          # Issue ref: https://github.com/actions/setup-python/issues/436
+          cache: "pip"
+      # setup and cache envs
+      - name: setup and cache envs
+        id: setup-envs
+        uses: ./.github/actions/setup-envs
+        with:
+          python-version: ${{ steps.setup-python.outputs.python-version }}
+          python-path: ${{ steps.setup-python.outputs.python-path }}
+          cache: true
+
+      - name: Build
+        run: hatch run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: ./site
+
+  deploy-docs:
+    needs: build-docs
+    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
+    permissions:
+      pages: write # to deploy to Pages
+      id-token: write # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v3

.github/workflows/lint-test.yml

@@ -0,0 +1,96 @@
+# WARNING: Do not change the name of this file, keep `lint-test.yml`.
+# `workflow_call` needs the name of the workflow file to work.
+
+name: Lint check and test
+
+# We only automatically run checks for PRs.
+# It is best to avoid direct commits to the main branch, instead make a PR for checks.
+# For the pushes to the main branch, the checks is done by `publish.yml` when publish.
+on:
+  pull_request:
+  workflow_dispatch:
+  # NOTE: set `secrets: inherit` when call this workflow from other workflow.
+  workflow_call:
+
+jobs:
+  lint-check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        id: setup-python
+        with:
+          python-version: ${{ matrix.python-version }}
+          # Issue ref: https://github.com/actions/setup-python/issues/436
+          cache: "pip"
+      # setup and cache envs
+      - name: setup and cache envs
+        id: setup-envs
+        uses: ./.github/actions/setup-envs
+        with:
+          python-version: ${{ steps.setup-python.outputs.python-version }}
+          python-path: ${{ steps.setup-python.outputs.python-path }}
+          cache: true
+
+      - name: Lint check and type check
+        # keep the hook name consistent with `ci.skip` in `.pre-commit-config.yaml`
+        run: |
+          pre-commit run type-check
+          pre-commit run fmt-check
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        os: ["ubuntu-latest", "windows-latest"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          # Issue ref: https://github.com/actions/setup-python/issues/436
+          cache: "pip"
+      # setup and cache envs
+      - name: setup and cache envs
+        id: setup-envs
+        uses: ./.github/actions/setup-envs
+        with:
+          python-version: ${{ steps.setup-python.outputs.python-version }}
+          # # https://github.com/actions/setup-python/blob/e9d6f990972a57673cdb72ec29e19d42ba28880f/docs/advanced-usage.md#environment-variables
+          python-path: ${{ steps.setup-python.outputs.python-path }}
+          cache: true
+
+      - name: Test
+        # Prevent unknown errors from causing long-term blockage of ci during testing
+        # can be adjusted according to the actual test time
+        timeout-minutes: 5
+        run: |
+          hatch run test
+      - name: Upload coverage reports to Codecov with GitHub Action
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          verbose: true
+          fail_ci_if_error: true
+
+  # https://github.com/marketplace/actions/alls-green#why
+  lint-test-all-green: # This job does nothing and is only used for the branch protection
+    if: always() # IMPORTANT: mandatory
+    needs:
+      - lint-check
+      - test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Decide whether the needed jobs succeeded or failed
+        uses: re-actors/alls-green@release/v1
+        with:
+          jobs: ${{ toJSON(needs) }}