Skip to content

Commit c00c7f6

Browse files
feat(pre-commit): Enhance pre-commit configuration and add quality requirements to CONTRIBUTING.md
- Introduced a new `.coverage` file for coverage reporting. - Updated `.pre-commit-config.yaml` to include additional hooks for strict linting and type checking, as well as basic testing for both Python and JavaScript. - Expanded the CONTRIBUTING.md file with a detailed quality requirements section, outlining code quality standards for Python and JavaScript contributions. - Added a testing strategy section to clarify the approach for testing and CI simulation.
1 parent a4ad55e commit c00c7f6

3 files changed

Lines changed: 199 additions & 54 deletions

File tree

.coverage

52 KB
Binary file not shown.

.pre-commit-config.yaml

Lines changed: 55 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -5,37 +5,84 @@ repos:
55
# Ruff version.
66
rev: v0.6.4
77
hooks:
8-
# Run the linter.
8+
# Run the linter with auto-fix (lenient on pre-commit)
99
- id: ruff
1010
args: [--fix]
11-
# Run the formatter.
11+
stages: [pre-commit]
12+
# Run the formatter
1213
- id: ruff-format
14+
stages: [pre-commit]
15+
# Strict linting for CI simulation (no auto-fix)
16+
- id: ruff
17+
name: ruff-check-strict
18+
args: [--no-fix]
19+
stages: [manual]
1320
- repo: https://github.com/pre-commit/mirrors-mypy
1421
rev: v1.11.2
1522
hooks:
23+
# Lenient mypy for pre-commit (basic type checking)
24+
- id: mypy
25+
name: mypy-basic
26+
entry: "mypy ./python"
27+
pass_filenames: false
28+
stages: [pre-commit]
29+
additional_dependencies:
30+
- "types-requests"
31+
- "pytest-asyncio"
32+
- "pydantic"
33+
- "marimo"
34+
# Strict mypy for CI simulation
1635
- id: mypy
36+
name: mypy-strict
1737
entry: "mypy --strict ./python"
1838
pass_filenames: false
39+
stages: [manual]
1940
additional_dependencies:
2041
- "types-requests"
2142
- "pytest-asyncio"
2243
- "pydantic"
2344
- "marimo"
2445
- repo: local
2546
hooks:
26-
- id: pytest-check
47+
# Basic Python tests on pre-push
48+
- id: pytest-basic
2749
stages: [pre-push]
2850
types: [python]
29-
name: pytest-check
30-
entry: python -m pytest -v python/tests/
51+
name: pytest-basic
52+
entry: python -m pytest python/tests/ -x
3153
language: system
3254
pass_filenames: false
3355
always_run: true
34-
- id: jest-tests
56+
# Basic JavaScript tests on pre-push
57+
- id: jest-basic
3558
stages: [pre-push]
3659
types: [javascript, jsx, ts, tsx]
37-
name: jest-tests
38-
entry: powershell -Command "Set-Location js; npm test"
60+
name: jest-basic
61+
entry: bash -c "cd js && npm test -- --passWithNoTests"
62+
language: system
63+
pass_filenames: false
64+
always_run: true
65+
# === CI SIMULATION HOOKS (run manually with: pre-commit run --hook-stage manual) ===
66+
- id: ci-check-python
67+
stages: [manual]
68+
name: ci-check-python
69+
entry: bash -c "python -m coverage run -m pytest -vv python/tests/ && python -m coverage report"
70+
language: system
71+
pass_filenames: false
72+
always_run: true
73+
types: [python]
74+
- id: ci-check-javascript
75+
stages: [manual]
76+
name: ci-check-javascript
77+
entry: bash -c "cd js && npm test"
78+
language: system
79+
pass_filenames: false
80+
always_run: true
81+
types: [javascript, jsx, ts, tsx]
82+
- id: ci-check-build-widgets
83+
stages: [manual]
84+
name: ci-check-build-widgets
85+
entry: bash -c "cd js && bash build-widgets.sh"
3986
language: system
4087
pass_filenames: false
4188
always_run: true

CONTRIBUTING.md

Lines changed: 144 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,79 @@ Thank you for your interest in contributing to Numerous Widgets! This document p
4545
echo "VITE_DEV_SERVER=http://localhost:5173" >> python/.env
4646
```
4747

48+
## ⚡ Quality Requirements & Standards
49+
50+
**We maintain high code quality standards to ensure reliability and maintainability.** All contributions must meet these requirements before being merged. We're transparent about what's expected - check the configuration files for exact specifications.
51+
52+
### 📋 Code Quality Checklist
53+
54+
Before contributing, ensure your code meets these standards:
55+
56+
**Python Requirements:**
57+
-**Linting**: Code passes [Ruff](https://github.com/astral-sh/ruff) checks
58+
-**Formatting**: Code is formatted with Ruff
59+
-**Type Safety**: All code has proper type annotations and passes MyPy strict mode
60+
-**Testing**: All new code has comprehensive tests with good coverage
61+
-**Documentation**: All public APIs are documented
62+
63+
**JavaScript/TypeScript Requirements:**
64+
-**Type Safety**: All TypeScript compiles without errors
65+
-**Testing**: All components have unit tests
66+
-**Build**: Widgets build successfully
67+
68+
**Configuration Files** (see exact requirements here):
69+
- 📁 [`.pre-commit-config.yaml`](.pre-commit-config.yaml) - Pre-commit hooks and quality checks
70+
- 📁 [`pyproject.toml`](pyproject.toml) - Python project configuration, Ruff rules, MyPy settings
71+
- 📁 [`js/package.json`](js/package.json) - JavaScript dependencies and scripts
72+
- 📁 [`js/tsconfig.json`](js/tsconfig.json) - TypeScript configuration
73+
- 📁 [`.github/workflows/release.yml`](.github/workflows/release.yml) - CI/CD pipeline requirements
74+
75+
### 🔧 Local Quality Checks
76+
77+
**Quick checks (run automatically on commit/push):**
78+
```bash
79+
# These run automatically via pre-commit hooks
80+
git commit -m "your changes" # Triggers basic formatting and linting
81+
git push # Triggers basic tests
82+
```
83+
84+
**Manual quality checks:**
85+
```bash
86+
# Run all basic checks
87+
pre-commit run --all-files
88+
89+
# Run specific checks
90+
cd js
91+
npm run lint # ESLint
92+
npm run typecheck # TypeScript
93+
npm test # Jest tests
94+
```
95+
96+
**CI simulation (run before creating PR):**
97+
```bash
98+
# Simulate full CI pipeline locally - this is what runs on GitHub Actions
99+
pre-commit run --hook-stage manual
100+
101+
# Or run individual CI checks:
102+
pre-commit run --hook-stage manual ruff-check-strict # Strict linting
103+
pre-commit run --hook-stage manual mypy-strict # Strict type checking
104+
pre-commit run --hook-stage manual ci-check-python # Python tests with coverage
105+
pre-commit run --hook-stage manual ci-check-javascript # JavaScript tests
106+
pre-commit run --hook-stage manual ci-check-build-widgets # Build verification
107+
```
108+
109+
### 📈 Quality Philosophy
110+
111+
We follow these principles:
112+
113+
1. **Transparency**: All requirements are clearly documented in config files
114+
2. **Developer Choice**: You control when to run strict checks
115+
3. **Fast Feedback**: Basic checks run quickly on commit/push
116+
4. **CI Confidence**: Local CI simulation helps avoid pipeline failures
117+
5. **Comprehensive Coverage**: All code paths are tested
118+
119+
**💡 Pro Tip**: Run `pre-commit run --hook-stage manual` before creating a PR to ensure CI will pass!
120+
48121
## 🏗️ Development Workflow
49122

50123
### Development Environment
@@ -72,32 +145,12 @@ This setup enables hot-reloading for both Python and JavaScript changes.
72145

73146
### Code Style and Linting
74147

75-
The project enforces strict code quality standards:
76-
77-
#### Python
78-
- **Ruff**: Linting and formatting
79-
- **MyPy**: Type checking
80-
- **Coverage**: Test coverage reporting
81-
82-
#### JavaScript/TypeScript
83-
- **ESLint**: Linting
84-
- **TypeScript**: Type checking
85-
- **Jest**: Testing framework
86-
87-
#### Running Quality Checks
148+
The project enforces strict code quality standards. **See the [Quality Requirements & Standards](#-quality-requirements--standards) section above for complete details.**
88149

89-
```bash
90-
# Run all checks (recommended before committing)
91-
pre-commit run --all-files
92-
93-
# Run specific checks
94-
cd js
95-
npm run lint # ESLint
96-
npm run typecheck # TypeScript
97-
npm test # Jest tests
98-
99-
# Python checks are handled by pre-commit hooks
100-
```
150+
Quick reference:
151+
- **Python**: Ruff (linting/formatting), MyPy (type checking), pytest (testing)
152+
- **JavaScript/TypeScript**: ESLint, TypeScript compiler, Jest (testing)
153+
- **All quality checks**: See configuration files linked above for exact specifications
101154

102155
## 🎨 Creating New Widgets
103156

@@ -520,56 +573,90 @@ pre-commit run --all-files
520573

521574
## 🧪 Testing
522575

576+
### Testing Strategy
577+
578+
We use a three-tier testing approach:
579+
580+
1. **Basic Tests** (run on pre-push): Fast, essential functionality
581+
2. **Comprehensive Tests** (run manually): Full test suite with coverage
582+
3. **CI Tests** (run on GitHub Actions): Production-ready validation
583+
523584
### Running Tests
524585

586+
**Basic testing** (fast, run automatically):
525587
```bash
526-
# Run all tests
527-
pre-commit run --all-files
588+
# Run basic tests (triggered on git push)
589+
git push
528590

529-
# Run Python tests only
530-
pytest python/tests/ -v
591+
# Or run manually
592+
pre-commit run pytest-basic jest-basic
593+
```
531594

532-
# Run JavaScript tests only
533-
cd js
534-
npm test
595+
**Comprehensive testing** (full coverage):
596+
```bash
597+
# Run all tests with coverage (CI simulation)
598+
pre-commit run --hook-stage manual ci-check-python ci-check-javascript
535599

536-
# Run tests with coverage
537-
cd js
538-
npm run test:coverage
600+
# Or run individual test suites
601+
pytest python/tests/ -v # Python tests
602+
cd js && npm test # JavaScript tests
603+
python -m coverage run -m pytest python/tests/ # Python with coverage
604+
```
605+
606+
**CI simulation** (exact match to GitHub Actions):
607+
```bash
608+
# Run complete CI pipeline locally
609+
pre-commit run --hook-stage manual
610+
611+
# This includes:
612+
# - Strict linting (ruff --no-fix)
613+
# - Strict type checking (mypy --strict)
614+
# - Python tests with coverage reporting
615+
# - JavaScript tests with npm ci
616+
# - Widget build verification
539617
```
540618

541619
### Test Requirements
542620

543-
- **Python**: Minimum 80% test coverage
621+
- **Python**: Minimum 80% test coverage (measured in CI)
544622
- **JavaScript**: All components should have unit tests
545623
- **Integration**: Test widget creation and basic functionality
546624
- **Type Safety**: All TypeScript must compile without errors
625+
- **Build**: Widgets must build successfully without errors
626+
627+
### Test File Organization
628+
629+
Follow these naming conventions:
630+
- **Python**: `python/tests/test_widget_name.py`
631+
- **Widget Component**: `js/src/components/widgets/__tests__/WidgetNameWidget.test.tsx`
632+
- **UI Component**: `js/src/components/ui/__tests__/ComponentName.test.tsx`
547633

548634
## 📋 Code Review Process
549635

550636
### Before Submitting
551637

552-
1. **Run all quality checks**:
638+
1. **Run CI simulation** (recommended):
553639
```bash
554-
pre-commit run --all-files
640+
# This runs the same checks as GitHub Actions
641+
pre-commit run --hook-stage manual
555642
```
556643

557-
2. **Test your changes**:
644+
2. **Alternative: Run individual checks**:
558645
```bash
646+
# Basic quality checks
647+
pre-commit run --all-files
648+
559649
# Test Python widgets
560650
pytest python/tests/
561651

562652
# Test JavaScript components
563653
cd js && npm test
654+
655+
# Build widgets
656+
cd js && bash build-widgets.sh
564657
```
565658

566-
3. **Build widgets**:
567-
```bash
568-
cd js
569-
./build-widgets.sh # or build-widgets.ps1 on Windows
570-
```
571-
572-
4. **Test in development environment**:
659+
3. **Test in development environment**:
573660
```bash
574661
# Start Vite dev server
575662
cd js && npm run dev
@@ -579,6 +666,17 @@ npm run test:coverage
579666
marimo edit app.py
580667
```
581668

669+
### 🎯 PR Readiness Checklist
670+
671+
Before creating your PR, ensure:
672+
673+
-**CI simulation passes**: `pre-commit run --hook-stage manual`
674+
-**All tests pass**: Both Python and JavaScript
675+
-**Widgets build successfully**: No build errors
676+
-**Code is documented**: New widgets have proper docstrings
677+
-**Tests are comprehensive**: New functionality is tested
678+
-**Examples work**: Test your changes in the development environment
679+
582680
### Pull Request Guidelines
583681

584682
1. **Title**: Use conventional commits format

0 commit comments

Comments
 (0)