Skip to content

Commit 6b32830

Browse files
karbassikarbassi
committed
spec
1 parent b1d243c commit 6b32830

3 files changed

Lines changed: 269 additions & 0 deletions

File tree

‎.kiro/specs/black-to-ruff-migration/design.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# Design Document
2+
3+
## Overview
4+
5+
This design outlines the migration from Black and isort to Ruff for the We All Code Django project. Ruff is a fast Python linter and formatter written in Rust that can replace both Black (formatting) and isort (import sorting) with a single tool. The migration will maintain existing code style preferences while consolidating tooling and improving performance.
6+
7+
## Architecture
8+
9+
### Tool Replacement Strategy
10+
11+
The migration follows a direct replacement approach:
12+
13+
- **Black** → **Ruff formatter** (maintains Black-compatible formatting)
14+
- **isort** → **Ruff import sorting** (maintains isort-compatible import organization)
15+
16+
### Configuration Approach
17+
18+
Ruff will be configured in `pyproject.toml` using the `[tool.ruff]` section with subsections for:
19+
20+
- General settings (line length, target Python version, exclusions)
21+
- Formatter settings (`[tool.ruff.format]`)
22+
- Import sorting settings (`[tool.ruff.isort]`)
23+
- Linting rules (`[tool.ruff.lint]`)
24+
25+
## Components and Interfaces
26+
27+
### Configuration Files
28+
29+
#### pyproject.toml Updates
30+
31+
- Remove `[tool.black]` section
32+
- Remove `[tool.isort]` section
33+
- Add comprehensive `[tool.ruff]` configuration
34+
- Add Ruff as a development dependency in the "# Development & Debugging" section alongside django-debug-toolbar
35+
36+
#### Pre-commit Configuration Updates
37+
38+
- Replace Black hook (currently using psf/black rev 23.3.0) with Ruff formatter hook
39+
- Replace isort hook (currently using pycqa/isort rev 5.12.0) with Ruff import sorting hook
40+
- Maintain existing exclusion patterns for migrations and .vscode folders
41+
- Keep all other pre-commit hooks unchanged (trailing-whitespace, end-of-file-fixer, etc.)
42+
43+
#### Documentation Updates
44+
45+
- Update `.kiro/steering/tech.md` Code Quality Tools section to reference Ruff instead of Black and isort
46+
- Update `.kiro/steering/structure.md` Development Conventions section to reference Ruff formatting
47+
- Check and update `README.md` if it contains references to Black or isort
48+
- Update any developer setup instructions to include Ruff-specific commands
49+
- Ensure all documentation maintains consistency with Ruff usage and 79-character line length
50+
51+
### Ruff Configuration Sections
52+
53+
Based on the current Black and isort configuration, Ruff will be configured as follows:
54+
55+
#### Core Settings
56+
57+
```toml
58+
[tool.ruff]
59+
line-length = 79
60+
target-version = "py311"
61+
exclude = [migrations, build artifacts, etc.]
62+
```
63+
64+
#### Formatter Settings
65+
66+
```toml
67+
[tool.ruff.format]
68+
quote-style = "double"
69+
indent-style = "space"
70+
skip-source-first-line = false
71+
line-ending = "auto"
72+
```
73+
74+
#### Import Sorting Settings
75+
76+
```toml
77+
[tool.ruff.isort]
78+
known-django = ["django"]
79+
section-order = ["future", "standard-library", "django", "third-party", "first-party", "local-folder"]
80+
combine-as-imports = true
81+
force-wrap-aliases = true
82+
split-on-trailing-comma = true
83+
```
84+
85+
#### Linting Rules
86+
87+
```toml
88+
[tool.ruff.lint]
89+
select = ["E", "F", "W", "I"] # Basic error, warning, and import rules
90+
ignore = [] # Project-specific ignores if needed
91+
```
92+
93+
## Data Models
94+
95+
No data models are affected by this migration as it only changes development tooling configuration.
96+
97+
## Error Handling
98+
99+
### Migration Validation
100+
101+
- Verify Ruff produces equivalent formatting to Black on existing codebase
102+
- Ensure import sorting maintains Django-aware section organization
103+
- Test pre-commit hooks function correctly with new configuration
104+
105+
### Rollback Strategy
106+
107+
- Keep backup of original Black/isort configuration
108+
- Document steps to revert if issues are discovered
109+
- Maintain git history for easy rollback
110+
111+
## Testing Strategy
112+
113+
### Configuration Testing
114+
115+
1. **Format Consistency Test**: Run Ruff formatter on existing codebase and verify minimal changes
116+
2. **Import Sorting Test**: Verify Ruff import sorting maintains Django section organization
117+
3. **Pre-commit Integration Test**: Test pre-commit hooks with Ruff configuration
118+
4. **Exclusion Pattern Test**: Verify migrations and other excluded files are not processed
119+
120+
### Validation Steps
121+
122+
1. Install Ruff and configure in pyproject.toml
123+
2. Run `ruff format --check` on codebase to verify compatibility
124+
3. Run `ruff check --select I` to test import sorting
125+
4. Test pre-commit hooks in isolated environment
126+
5. Compare output with existing Black/isort formatting
127+
128+
### Performance Verification
129+
130+
- Measure formatting speed improvement with Ruff vs Black+isort
131+
- Verify pre-commit hook execution time improvement
132+
133+
## Implementation Considerations
134+
135+
### Dependency Management
136+
137+
- Ruff will be added to the "# Development & Debugging" section in pyproject.toml dependencies (following the existing organizational pattern where development tools like django-debug-toolbar are grouped)
138+
- Black and isort configurations will be removed from pyproject.toml (they are not explicitly listed as dependencies, only configured)
139+
- uv will handle Ruff installation and version management
140+
- Ruff will be placed appropriately within the development tools section to maintain logical grouping
141+
142+
### Backward Compatibility
143+
144+
- Ruff's Black-compatible formatter ensures existing code style is maintained
145+
- Django-aware import sorting preserves current import organization
146+
- Line length and exclusion patterns remain unchanged
147+
148+
### Team Adoption
149+
150+
- Developers will need to update their local pre-commit hooks
151+
- IDE integrations may need to be updated to use Ruff instead of Black
152+
- Documentation will guide developers through the transition

‎.kiro/specs/black-to-ruff-migration/requirements.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Requirements Document
2+
3+
## Introduction
4+
5+
This feature involves migrating the We All Code Django project from using Black (code formatter) and isort (import sorter) to Ruff, which is a faster, all-in-one Python linter and formatter that can replace both tools. Ruff provides the same formatting capabilities as Black while also offering linting and import sorting functionality in a single, faster tool.
6+
7+
## Requirements
8+
9+
### Requirement 1: Tool Replacement
10+
11+
**User Story:** As a developer, I want to use Ruff instead of Black and isort, so that I have faster code formatting and linting with a single tool.
12+
13+
#### Acceptance Criteria
14+
15+
1. WHEN the project is configured THEN Ruff SHALL replace Black as the code formatter
16+
2. WHEN the project is configured THEN Ruff SHALL replace isort for import sorting
17+
3. WHEN Ruff is configured THEN it SHALL maintain the existing 79-character line length
18+
4. WHEN Ruff is configured THEN it SHALL exclude migrations from formatting (same as current Black config)
19+
5. WHEN Ruff is configured THEN it SHALL maintain Django-aware import sorting sections
20+
21+
### Requirement 2: Pre-commit Integration
22+
23+
**User Story:** As a developer, I want the pre-commit hooks updated to use Ruff, so that code quality checks run automatically before commits.
24+
25+
#### Pre-commit Acceptance Criteria
26+
27+
1. WHEN pre-commit hooks are updated THEN they SHALL use Ruff instead of Black and isort
28+
2. WHEN pre-commit runs THEN it SHALL format code using Ruff
29+
3. WHEN pre-commit runs THEN it SHALL sort imports using Ruff
30+
4. WHEN pre-commit runs THEN it SHALL maintain the same exclusion patterns as before
31+
32+
### Requirement 3: Documentation Updates
33+
34+
**User Story:** As a developer, I want all project documentation updated to reflect the Ruff migration, so that new contributors understand the current tooling and existing developers have accurate reference materials.
35+
36+
#### Documentation Acceptance Criteria
37+
38+
1. WHEN documentation is updated THEN .kiro/steering/tech.md SHALL reference Ruff instead of Black and isort in the Code Quality Tools section
39+
2. WHEN documentation is updated THEN .kiro/steering/structure.md SHALL reference Ruff formatting conventions instead of Black
40+
3. WHEN documentation is updated THEN README.md SHALL be updated if it contains references to Black or isort
41+
4. WHEN documentation is updated THEN any developer setup instructions SHALL include Ruff-specific commands
42+
5. WHEN documentation is updated THEN all references to code formatting tools SHALL be consistent with Ruff usage
43+
6. WHEN documentation is updated THEN it SHALL maintain accuracy about the 79-character line length requirement
44+
45+
### Requirement 4: Dependency Management
46+
47+
**User Story:** As a developer, I want Ruff to be added as a project dependency, so that it's available in the development environment.
48+
49+
#### Dependency Acceptance Criteria
50+
51+
1. WHEN dependencies are updated THEN Ruff SHALL be added to pyproject.toml
52+
2. WHEN dependencies are updated THEN Black and isort SHALL be removed from dependencies (if present)
53+
3. WHEN Ruff is added THEN it SHALL be in the appropriate dependency group for development tools
54+
4. WHEN the configuration is complete THEN Ruff SHALL be usable via uv commands

‎.kiro/specs/black-to-ruff-migration/tasks.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Implementation Plan
2+
3+
- [ ] 1. Configure Ruff in pyproject.toml
4+
5+
- Remove existing [tool.black] and [tool.isort] configuration sections
6+
- Add comprehensive [tool.ruff] configuration with general settings (line-length = 79, target-version = "py311", exclude migrations)
7+
- Add [tool.ruff.format] section with Black-compatible settings (quote-style = "double", indent-style = "space")
8+
- Add [tool.ruff.isort] section with Django-aware import sorting (known-django, section-order, combine-as-imports)
9+
- Add [tool.ruff.lint] section with basic linting rules (select = ["E", "F", "W", "I"])
10+
- Add Ruff as a development dependency in the "# Development & Debugging" section alongside django-debug-toolbar
11+
- _Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 4.1, 4.2, 4.3, 4.4_
12+
13+
- [ ] 2. Update pre-commit configuration
14+
15+
- Replace Black hook (psf/black) with Ruff formatter hook (charliermarsh/ruff-pre-commit)
16+
- Replace isort hook (pycqa/isort) with Ruff import sorting hook using --select I flag
17+
- Maintain existing exclusion patterns for migrations and .vscode folders
18+
- Keep all other pre-commit hooks unchanged (trailing-whitespace, end-of-file-fixer, etc.)
19+
- _Requirements: 2.1, 2.2, 2.3, 2.4_
20+
21+
- [ ] 3. Update documentation files
22+
- [ ] 3.1 Update .kiro/steering/tech.md
23+
24+
- Replace Black and isort references with Ruff in Code Quality Tools section
25+
- Update tool descriptions to reflect Ruff's combined formatting and linting capabilities
26+
- Maintain 79-character line length documentation
27+
- _Requirements: 3.1, 3.6_
28+
29+
- [ ] 3.2 Update .kiro/steering/structure.md
30+
31+
- Replace Black formatter references with Ruff in Development Conventions section
32+
- Update code style documentation to reference Ruff instead of Black and isort
33+
- Maintain Django-aware import sorting documentation
34+
- _Requirements: 3.2, 3.6_
35+
36+
- [ ] 3.3 Check and update README.md if needed
37+
38+
- Search for any references to Black or isort in README.md
39+
- Update developer setup instructions to include Ruff-specific commands if present
40+
- Ensure consistency with Ruff usage throughout documentation
41+
- _Requirements: 3.3, 3.4, 3.5_
42+
43+
- [ ] 4. Test Ruff configuration
44+
- [ ] 4.1 Validate formatting compatibility
45+
46+
- Run `ruff format --check` on existing codebase to verify minimal changes
47+
- Compare Ruff output with current Black formatting to ensure consistency
48+
- Test that 79-character line length is maintained
49+
- Verify migrations are excluded from formatting
50+
- _Requirements: 1.1, 1.3, 1.4_
51+
52+
- [ ] 4.2 Validate import sorting
53+
54+
- Run `ruff check --select I` to test import sorting functionality
55+
- Verify Django-aware section organization is maintained
56+
- Test that import sorting follows isort-compatible behavior
57+
- _Requirements: 1.2, 1.5_
58+
59+
- [ ] 4.3 Test pre-commit integration
60+
- Run pre-commit hooks in isolated environment to verify functionality
61+
- Test that Ruff hooks execute correctly and maintain exclusion patterns
62+
- Verify pre-commit performance improvement with Ruff
63+
- _Requirements: 2.1, 2.2, 2.3, 2.4_

0 commit comments

Comments
 (0)