@@ -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
5846821 . ** Title** : Use conventional commits format
0 commit comments