Skip to content

Commit a29c84b

Browse files
diraoldiraol
committed
Phase 6.1: Create migration guide and update plan
- Create comprehensive MIGRATION_GUIDE.md: * Quick start guide * Configuration mapping * Step-by-step migration instructions * Common scenarios and troubleshooting * Breaking changes documentation * Rollback instructions - Update RUFF_MIGRATION_PLAN.md: * Mark Task 6.1 documentation items as complete * Note that migration guide is created * Note that Ruff-specific features are documented
1 parent 7214fd3 commit a29c84b

2 files changed

Lines changed: 291 additions & 4 deletions

File tree

‎MIGRATION_GUIDE.md‎

Lines changed: 287 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,287 @@
1+
# Migration Guide: From Old Linting Tools to Ruff
2+
3+
This guide helps you migrate from the old python-mode linting configuration (using pylint, pyflakes, pycodestyle, etc.) to the new Ruff-based system.
4+
5+
## Overview
6+
7+
Python-mode now uses **Ruff** instead of multiple separate linting tools. Ruff is:
8+
- **10-100x faster** than the old tools
9+
- **Single unified tool** replacing pyflakes, pycodestyle, mccabe, pylint, pydocstyle, autopep8
10+
- **Backward compatible** - your existing configuration is automatically mapped to Ruff rules
11+
12+
## Quick Start
13+
14+
### 1. Install Ruff
15+
16+
```bash
17+
pip install ruff
18+
```
19+
20+
Verify installation:
21+
```bash
22+
ruff --version
23+
```
24+
25+
### 2. Your Existing Configuration Still Works!
26+
27+
The good news: **You don't need to change anything immediately**. Your existing `g:pymode_lint_*` options are automatically mapped to Ruff rules.
28+
29+
For example:
30+
```vim
31+
" Your old configuration still works!
32+
let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle', 'mccabe']
33+
let g:pymode_lint_ignore = ["E501", "W"]
34+
```
35+
36+
This is automatically converted to equivalent Ruff rules.
37+
38+
### 3. (Optional) Migrate to Ruff-Specific Options
39+
40+
For better control and performance, you can migrate to Ruff-specific options:
41+
42+
```vim
43+
" Enable Ruff linting and formatting
44+
let g:pymode_ruff_enabled = 1
45+
let g:pymode_ruff_format_enabled = 1
46+
47+
" Ruff-specific ignore rules (takes precedence over g:pymode_lint_ignore)
48+
let g:pymode_ruff_ignore = ["E501", "W"]
49+
50+
" Ruff-specific select rules (takes precedence over g:pymode_lint_select)
51+
let g:pymode_ruff_select = []
52+
53+
" Optional: Specify Ruff config file
54+
let g:pymode_ruff_config_file = ""
55+
```
56+
57+
## Configuration Mapping
58+
59+
### Legacy Options → Ruff Rules
60+
61+
| Old Option | Ruff Equivalent | Notes |
62+
|------------|----------------|-------|
63+
| `g:pymode_lint_checkers = ['pyflakes']` | Ruff F rules | F401, F402, F403, etc. |
64+
| `g:pymode_lint_checkers = ['pycodestyle']` | Ruff E/W rules | E501, W292, etc. |
65+
| `g:pymode_lint_checkers = ['mccabe']` | Ruff C90 rules | C901 (complexity) |
66+
| `g:pymode_lint_checkers = ['pylint']` | Ruff PLE/PLR/PLW rules | PLE0001, PLR0913, etc. |
67+
| `g:pymode_lint_checkers = ['pep257']` | Ruff D rules | D100, D101, etc. |
68+
| `g:pymode_lint_ignore = ["E501"]` | Ruff ignore E501 | Same rule code |
69+
| `g:pymode_lint_select = ["W0011"]` | Ruff select W0011 | Same rule code |
70+
71+
**Note:** Rule codes are mostly compatible. See `RUFF_CONFIGURATION_MAPPING.md` for detailed mappings.
72+
73+
### Using Ruff Configuration Files
74+
75+
Ruff supports configuration via `pyproject.toml` or `ruff.toml`:
76+
77+
**pyproject.toml:**
78+
```toml
79+
[tool.ruff]
80+
line-length = 88
81+
select = ["E", "F", "W"]
82+
ignore = ["E501"]
83+
84+
[tool.ruff.lint]
85+
select = ["E", "F", "W"]
86+
ignore = ["E501"]
87+
```
88+
89+
**ruff.toml:**
90+
```toml
91+
line-length = 88
92+
select = ["E", "F", "W"]
93+
ignore = ["E501"]
94+
```
95+
96+
Python-mode will automatically use these files if they exist in your project root.
97+
98+
## Step-by-Step Migration
99+
100+
### Step 1: Verify Ruff Installation
101+
102+
```bash
103+
pip install ruff
104+
ruff --version
105+
```
106+
107+
### Step 2: Test Your Current Setup
108+
109+
Your existing configuration should work immediately. Try:
110+
```vim
111+
:PymodeLint " Should work with Ruff
112+
:PymodeLintAuto " Should format with Ruff
113+
```
114+
115+
### Step 3: (Optional) Create Ruff Config File
116+
117+
Create `pyproject.toml` or `ruff.toml` in your project root:
118+
119+
```toml
120+
[tool.ruff]
121+
line-length = 88
122+
select = ["E", "F", "W"]
123+
ignore = ["E501"]
124+
```
125+
126+
### Step 4: (Optional) Migrate to Ruff-Specific Options
127+
128+
Update your `.vimrc`:
129+
130+
```vim
131+
" Old way (still works)
132+
let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle']
133+
let g:pymode_lint_ignore = ["E501"]
134+
135+
" New way (recommended)
136+
let g:pymode_ruff_enabled = 1
137+
let g:pymode_ruff_format_enabled = 1
138+
let g:pymode_ruff_ignore = ["E501"]
139+
```
140+
141+
## Common Scenarios
142+
143+
### Scenario 1: Using pyflakes + pycodestyle
144+
145+
**Before:**
146+
```vim
147+
let g:pymode_lint_checkers = ['pyflakes', 'pycodestyle']
148+
let g:pymode_lint_ignore = ["E501"]
149+
```
150+
151+
**After (automatic):**
152+
- Works immediately, no changes needed!
153+
154+
**After (Ruff-specific):**
155+
```vim
156+
let g:pymode_ruff_enabled = 1
157+
let g:pymode_ruff_ignore = ["E501"]
158+
" Ruff automatically includes F (pyflakes) and E/W (pycodestyle) rules
159+
```
160+
161+
### Scenario 2: Using autopep8 for formatting
162+
163+
**Before:**
164+
```vim
165+
" autopep8 was used automatically by :PymodeLintAuto
166+
```
167+
168+
**After:**
169+
```vim
170+
let g:pymode_ruff_format_enabled = 1
171+
" :PymodeLintAuto now uses Ruff format (faster!)
172+
```
173+
174+
### Scenario 3: Custom pylint configuration
175+
176+
**Before:**
177+
```vim
178+
let g:pymode_lint_checkers = ['pylint']
179+
let g:pymode_lint_options_pylint = {'max-line-length': 100}
180+
```
181+
182+
**After:**
183+
```vim
184+
let g:pymode_ruff_enabled = 1
185+
" Use pyproject.toml for Ruff configuration:
186+
" [tool.ruff]
187+
" line-length = 100
188+
" select = ["PLE", "PLR", "PLW"] # pylint rules
189+
```
190+
191+
## Troubleshooting
192+
193+
### Ruff not found
194+
195+
**Error:** `ruff: command not found`
196+
197+
**Solution:**
198+
```bash
199+
pip install ruff
200+
# Verify:
201+
ruff --version
202+
```
203+
204+
### Different formatting output
205+
206+
**Issue:** Ruff formats code differently than autopep8
207+
208+
**Solution:** This is expected. Ruff follows PEP 8 and Black formatting style. If you need specific formatting, configure Ruff via `pyproject.toml`:
209+
210+
```toml
211+
[tool.ruff.format]
212+
quote-style = "double"
213+
indent-style = "space"
214+
```
215+
216+
### Rule codes don't match
217+
218+
**Issue:** Some rule codes might differ between old tools and Ruff
219+
220+
**Solution:** See `RUFF_CONFIGURATION_MAPPING.md` for detailed rule mappings. Most common rules (E501, F401, etc.) are compatible.
221+
222+
### Performance issues
223+
224+
**Issue:** Linting seems slower than expected
225+
226+
**Solution:**
227+
1. Ensure Ruff is installed: `pip install ruff`
228+
2. Check if legacy options are causing overhead (migrate to Ruff-specific options)
229+
3. Verify Ruff config file is being used
230+
231+
## Breaking Changes
232+
233+
### Removed Tools
234+
235+
The following tools are **no longer available** as separate checkers:
236+
- `pylint` (use Ruff PLE/PLR/PLW rules)
237+
- `pyflakes` (use Ruff F rules)
238+
- `pycodestyle` (use Ruff E/W rules)
239+
- `mccabe` (use Ruff C90 rules)
240+
- `pep257` (use Ruff D rules)
241+
- `autopep8` (use Ruff format)
242+
243+
### Configuration Changes
244+
245+
- `g:pymode_lint_checkers` values are mapped to Ruff rules (not actual tools)
246+
- `g:pymode_lint_options_*` are mapped to Ruff configuration
247+
- Old tool-specific options may not have exact equivalents
248+
249+
### Behavior Changes
250+
251+
- **Formatting:** Ruff format may produce slightly different output than autopep8
252+
- **Linting:** Ruff may report different errors than pylint/pyflakes (usually fewer false positives)
253+
- **Performance:** Should be significantly faster
254+
255+
## Rollback Instructions
256+
257+
If you need to rollback to the old system:
258+
259+
1. **Checkout previous version:**
260+
```bash
261+
git checkout <previous-version-tag>
262+
```
263+
264+
2. **Reinstall old dependencies** (if needed):
265+
```bash
266+
pip install pylint pyflakes pycodestyle mccabe pydocstyle autopep8
267+
```
268+
269+
3. **Restore old configuration** in your `.vimrc`
270+
271+
**Note:** The old tools are no longer maintained as submodules. You'll need to install them separately if rolling back.
272+
273+
## Need Help?
274+
275+
- **Configuration mapping:** See `RUFF_CONFIGURATION_MAPPING.md`
276+
- **Ruff documentation:** https://docs.astral.sh/ruff/
277+
- **Ruff rules:** https://docs.astral.sh/ruff/rules/
278+
- **Python-mode help:** `:help pymode-ruff-configuration`
279+
280+
## Summary
281+
282+
✅ **No immediate action required** - your existing config works
283+
✅ **Install Ruff:** `pip install ruff`
284+
✅ **Optional:** Migrate to Ruff-specific options for better control
285+
✅ **Use Ruff config files:** `pyproject.toml` or `ruff.toml` for project-specific settings
286+
✅ **Enjoy faster linting and formatting!**
287+

‎RUFF_MIGRATION_PLAN.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -154,11 +154,11 @@ This document outlines a comprehensive plan to replace most of the python-mode s
154154
**Timeline: 1-2 weeks**
155155

156156
#### Task 6.1: Update Documentation
157-
- [ ] Update `doc/pymode.txt` with ruff information
157+
- [x] Update `doc/pymode.txt` with ruff information (✅ Complete)
158158
- [ ] Create migration guide from old configuration
159-
- [ ] Document new ruff-specific features
160-
- [ ] Update README.md with new requirements
161-
- [ ] Add troubleshooting section
159+
- [x] Document new ruff-specific features (✅ In doc/pymode.txt section 3.1)
160+
- [x] Update README.md with new requirements (✅ Done in Phase 2)
161+
- [x] Add troubleshooting section (✅ Added to FAQ section)
162162

163163
#### Task 6.2: Provide Migration Tools
164164
- [ ] Create configuration converter script

0 commit comments

Comments
 (0)