feat: set up Copilot agent environment with uv, pre-commit, and GitHub Actions workflow (#536)

This PR sets up the Copilot agent environment following GitHub's
official documentation to improve the development experience for
AI-assisted coding.

## Changes Made

**Copilot Setup Workflow:**
- Created `.github/workflows/copilot-setup-steps.yml` following GitHub's
official documentation and example structure
- Added proper workflow triggers (workflow_dispatch, push, pull_request)
with path filtering for easy validation
- Configured minimal permissions (`contents: read`) as recommended by
GitHub
- Pre-configures Copilot's environment with Python 3.11, uv package
manager, and all project dependencies
- Installs development tools (pre-commit, pyright) and sets up
pre-commit hooks automatically
- Uses pip-based uv installation to avoid network restrictions in
Copilot environment
- Verifies installation to ensure environment is properly configured
before agent starts

**Environment Setup:**
- Implemented `uv` for Python environment and dependency management
(faster than pip)
- Added `uv tool install` for development tools (`pre-commit`,
`pyright`)
- Configured `pre-commit` as the preferred tool for code quality checks

**Updated Copilot Instructions:**
- Modified `.github/copilot-instructions.md` to prefer `pre-commit run
--all-files` over direct `ruff` usage
- Added comprehensive Copilot agent environment setup section
- Updated validation workflow to use modern tooling
- Added fallback instructions for network-restricted environments

**Configuration Fixes:**
- Updated `pyproject.toml` to use modern ruff configuration format
(`[tool.ruff.lint]`)
- Eliminated deprecation warnings about top-level linter settings
- Removed deprecated `ignore-init-module-imports` option

## Benefits

- **Reliable agent environment** through pre-configured workflow steps
that run before the agent starts
- **Faster dependency resolution** with `uv` package manager
- **Network restriction compatibility** by avoiding blocked domains
during setup
- **Comprehensive code quality checks** through pre-commit hooks (ruff,
prettier, velin, blacken-docs)
- **Better developer experience** for Copilot agents with proper tool
installation
- **Modern tooling practices** following GitHub's recommendations
- **Consistent code quality** across all contributors

The copilot-setup-steps.yml workflow ensures that Copilot agents have a
deterministic, fast, and reliable environment setup instead of relying
on trial-and-error dependency discovery.

Fixes #535.

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for
you](https://github.com/deepmodeling/dpdispatcher/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot)
— coding agent works faster and does higher quality work when set up for
your repo.

---------

Co-authored-by: copilot-swe-agent[bot] <[email protected]>
Co-authored-by: njzjz <[email protected]>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

.github/copilot-instructions.md

@@ -13,7 +13,9 @@ Always reference these instructions first and fallback to search or bash command
   ```bash
   uv venv .venv
   source .venv/bin/activate
-  uv pip install .[test] coverage ruff pre-commit
+  uv pip install .[test] coverage
+  uv tool install pre-commit
+  uv tool install pyright
   ```
 
 - **Run the test suite:**
@@ -29,11 +31,11 @@ Always reference these instructions first and fallback to search or bash command
 - **Run linting and formatting:**
 
   ```bash
-  ruff check .
-  ruff format --check .
+  pre-commit run --all-files
   ```
 
-  - **TIMING: Linting takes <1 second.**
+  - **TIMING: Linting takes <5 seconds.**
+  - **Fallback:** If pre-commit fails with network issues, use `ruff check . && ruff format --check .`
 
 - **Run type checking:**
 
@@ -53,6 +55,24 @@ Always reference these instructions first and fallback to search or bash command
 
   - **TIMING: Documentation build takes ~14 seconds.**
 
+### Copilot Agent Environment Setup
+
+Following GitHub's Copilot agent environment guidelines, this project uses:
+
+- **`uv`** for Python environment and dependency management
+- **`uv tool install`** for development tools (`pre-commit`, `pyright`)
+- **`pre-commit`** for automated code quality checks (preferred over direct tool usage)
+
+```bash
+# Initial setup
+uv venv .venv
+source .venv/bin/activate
+uv pip install .[test] coverage
+uv tool install pre-commit
+uv tool install pyright
+pre-commit install --install-hooks
+```
+
 ### CLI Usage
 
 - **Test basic CLI functionality:**
@@ -70,7 +90,7 @@ Always reference these instructions first and fallback to search or bash command
 ## Validation
 
 - **ALWAYS run the test suite after making code changes.** Tests execute quickly (~25 seconds) and should never be cancelled.
-- **ALWAYS run linting before committing:** `ruff check . && ruff format --check .`
+- **ALWAYS run linting before committing:** `pre-commit run --all-files`
 - **ALWAYS run type checking:** `pyright` to catch type-related issues.
 - **Test CLI functionality:** Run `dpdisp --help` and test with example scripts to ensure the CLI works correctly.
 - **Build documentation:** Run `make html` in the `doc/` directory to verify documentation builds without errors.
@@ -81,7 +101,7 @@ Always reference these instructions first and fallback to search or bash command
 - **Build system:** Uses `setuptools` with `pyproject.toml` configuration.
 - **Python versions:** Supports Python 3.7+ (check `pyproject.toml` for current support matrix).
 - **Testing:** Uses `unittest` framework with coverage reporting.
-- **Linting:** Uses `ruff` for both linting and formatting.
+- **Linting:** Uses `pre-commit` with `ruff` for linting and formatting, plus other quality checks.
 - **Type checking:** Uses `pyright` for static type analysis (configured in `pyproject.toml`).
 - **Documentation:** Uses Sphinx with MyST parser for markdown support.
 
@@ -161,13 +181,14 @@ dpdisp run examples/dpdisp_run.py
 - **Always add type hints** - Include proper type annotations in all Python code for better maintainability
 - **Always use conventional commit format** - All commit messages and PR titles must follow the conventional commit specification (e.g., `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`)
 - **Test artifacts are gitignored** - Job execution creates temporary files that are automatically excluded
-- **Pre-commit hooks available** - Use `pre-commit install` to enable automated code quality checks
+- **Pre-commit hooks available** - Use `pre-commit install --install-hooks` to enable automated code quality checks
 - **Multiple execution contexts** - Code supports local execution, SSH remote execution, and various HPC schedulers
 - **Extensive examples** - Use `examples/` directory as reference for proper configuration formats
 
 ## Troubleshooting
 
 - **Virtual environment issues:** Always use `uv venv .venv` and `source .venv/bin/activate`
+- **Tool installation:** Use `uv tool install pre-commit` and `uv tool install pyright` for dev tools
 - **Test failures:** Most tests run locally; some require specific HPC environments and will be skipped
 - **Documentation build warnings:** Some warnings about external inventory URLs are expected in sandboxed environments
 - **Pre-commit network issues:** If pre-commit fails with network timeouts, run `ruff check` and `ruff format` directly

.github/workflows/copilot-setup-steps.yml

@@ -0,0 +1,65 @@
+name: "Copilot Setup Steps"
+
+# Automatically run the setup steps when they are changed to allow for easy validation, and
+# allow manual testing through the repository's "Actions" tab
+on:
+  workflow_dispatch:
+  push:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+  pull_request:
+    paths:
+      - .github/workflows/copilot-setup-steps.yml
+
+jobs:
+  # The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+
+    # Set the permissions to the lowest permissions possible needed for your steps.
+    # Copilot will be given its own token for its operations.
+    permissions:
+      # If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
+      contents: read
+
+    # You can define any steps you want, and they will run before the agent starts.
+    # If you do not check out your code, Copilot will do this for you.
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        run: |
+          # Install uv using pip to avoid network restrictions
+          python -m pip install --upgrade pip
+          python -m pip install uv
+
+      - name: Create virtual environment and install dependencies
+        run: |
+          uv venv .venv
+          source .venv/bin/activate
+          uv pip install .[test] coverage
+
+      - name: Install development tools
+        run: |
+          uv tool install pre-commit
+          uv tool install pyright
+
+      - name: Set up pre-commit hooks
+        run: |
+          source .venv/bin/activate
+          pre-commit install --install-hooks
+
+      - name: Verify installation
+        run: |
+          source .venv/bin/activate
+          python --version
+          uv --version
+          pre-commit --version
+          pyright --version
+          python -c "import dpdispatcher; print('DPDispatcher installed successfully')"

pyproject.toml

@@ -82,7 +82,7 @@ exclude = [
 [tool.isort]
 profile = "black"
 
-[tool.ruff]
+[tool.ruff.lint]
 select = [
     "E", # errors
     "F", # pyflakes
@@ -110,7 +110,6 @@ ignore = [
     "D401", # TODO: first line should be in imperative mood
     "D404", # TODO: first word of the docstring should not be This
 ]
-ignore-init-module-imports = true
 
-[tool.ruff.pydocstyle]
+[tool.ruff.lint.pydocstyle]
 convention = "numpy"