chore: import upstream snapshot with attribution

2026-07-13 12:40:22 +08:00
commit 9963ea7ef7
410 changed files with 85021 additions and 0 deletions
@@ -0,0 +1,158 @@
+# GitHub Actions Workflows
+
+This directory contains CI/CD workflows for SuperClaude Framework.
+
+## Workflows
+
+### 1. **test.yml** - Comprehensive Test Suite
+**Triggers**: Push/PR to `master` or `integration`, manual dispatch
+**Jobs**:
+- **test**: Run tests on Python 3.10, 3.11, 3.12
+  - Install UV and dependencies
+  - Run full test suite
+  - Generate coverage report (Python 3.10 only)
+  - Upload to Codecov
+- **lint**: Run ruff linter and format checker
+- **plugin-check**: Verify pytest plugin loads correctly
+- **doctor-check**: Run `superclaude doctor` health check
+- **test-summary**: Aggregate results from all jobs
+
+**Status Badge**:
+```markdown
+[![Tests](https://github.com/SuperClaude-Org/SuperClaude_Framework/actions/workflows/test.yml/badge.svg)](https://github.com/SuperClaude-Org/SuperClaude_Framework/actions/workflows/test.yml)
+```
+
+### 2. **quick-check.yml** - Fast PR Feedback
+**Triggers**: Pull requests to `master` or `integration`
+**Jobs**:
+- **quick-test**: Fast check on Python 3.10 only
+  - Run unit tests only (faster)
+  - Run linter
+  - Check formatting
+  - Verify plugin loads
+  - 10 minute timeout
+
+**Purpose**: Provide rapid feedback on PRs before running full test matrix.
+
+### 3. **publish-pypi.yml** (Existing)
+**Triggers**: Manual or release tags
+**Purpose**: Publish package to PyPI
+
+### 4. **readme-quality-check.yml** (Existing)
+**Triggers**: Push/PR affecting README files
+**Purpose**: Validate README quality and consistency
+
+## Local Testing
+
+Before pushing, run these commands locally:
+
+```bash
+# Run full test suite
+uv run pytest -v
+
+# Run with coverage
+uv run pytest --cov=superclaude --cov-report=term
+
+# Run linter
+uv run ruff check src/ tests/
+
+# Check formatting
+uv run ruff format --check src/ tests/
+
+# Auto-fix formatting
+uv run ruff format src/ tests/
+
+# Verify plugin loads
+uv run pytest --trace-config | grep superclaude
+
+# Run doctor check
+uv run superclaude doctor --verbose
+```
+
+## CI/CD Pipeline
+
+```
+┌─────────────────────┐
+│   Push/PR Created   │
+└──────────┬──────────┘
+           │
+           ├─────────────────────────┐
+           │                         │
+    ┌──────▼──────┐         ┌───────▼────────┐
+    │ Quick Check │         │  Full Test     │
+    │  (PR only)  │         │   Matrix       │
+    │             │         │                │
+    │ • Unit tests│         │ • Python 3.10  │
+    │ • Lint      │         │ • Python 3.11  │
+    │ • Format    │         │ • Python 3.12  │
+    │             │         │ • Coverage     │
+    │ ~2-3 min    │         │ • Lint         │
+    └─────────────┘         │ • Plugin check │
+                            │ • Doctor check │
+                            │                │
+                            │ ~5-8 min       │
+                            └────────────────┘
+```
+
+## Coverage Reporting
+
+Coverage reports are generated for Python 3.10 and uploaded to Codecov.
+
+To view coverage locally:
+```bash
+uv run pytest --cov=superclaude --cov-report=html
+open htmlcov/index.html
+```
+
+## Troubleshooting
+
+### Workflow fails with "UV not found"
+- UV is installed in each job via `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- If installation fails, check UV's status page
+
+### Tests fail locally but pass in CI (or vice versa)
+- Check Python version: `python --version`
+- Reinstall dependencies: `uv pip install -e ".[dev]"`
+- Clear caches: `rm -rf .pytest_cache .venv`
+
+### Plugin not loading in CI
+- Verify entry point in `pyproject.toml`: `[project.entry-points.pytest11]`
+- Check plugin is installed: `uv run pytest --trace-config`
+
+### Coverage upload fails
+- This is non-blocking (fail_ci_if_error: false)
+- Check Codecov token in repository secrets
+
+## Maintenance
+
+### Adding a New Workflow
+1. Create new `.yml` file in this directory
+2. Follow existing structure (checkout, setup-python, install UV)
+3. Add status badge to README.md if needed
+4. Document in this file
+
+### Updating Python Versions
+1. Edit `matrix.python-version` in `test.yml`
+2. Update `pyproject.toml` classifiers
+3. Test locally with new version first
+
+### Modifying Test Strategy
+- **quick-check.yml**: For fast PR feedback (unit tests only)
+- **test.yml**: For comprehensive validation (full matrix)
+
+## Best Practices
+
+1. **Keep workflows fast**: Use caching, parallel jobs
+2. **Fail fast**: Use `-x` flag in pytest for quick-check
+3. **Clear names**: Job and step names should be descriptive
+4. **Version pinning**: Pin action versions (@v4, @v5)
+5. **Matrix testing**: Test on multiple Python versions
+6. **Non-blocking coverage**: Don't fail on coverage upload errors
+7. **Manual triggers**: Add `workflow_dispatch` for debugging
+
+## Resources
+
+- [GitHub Actions Documentation](https://docs.github.com/en/actions)
+- [UV Documentation](https://github.com/astral-sh/uv)
+- [Pytest Documentation](https://docs.pytest.org/)
+- [SuperClaude Testing Guide](../../docs/developer-guide/testing-debugging.md)