This document outlines a comprehensive plan to replace most of the python-mode submodules with Ruff, a blazingly fast Python linter and formatter written in Rust. The migration will reduce complexity, improve performance, and modernize the codebase while preserving essential functionality.

- **pyflakes** - Syntax errors and undefined names detection

- **pycodestyle** - PEP 8 style guide enforcement

- **mccabe** - Cyclomatic complexity checking

- **pylint** - Comprehensive static analysis

- **pydocstyle** - Docstring style checking

- **pylama** - Multi-tool linting wrapper

- **autopep8** - Automatic PEP 8 formatting

- **rope** - Refactoring, completion, and code intelligence *(essential for IDE features)*

- **astroid** - Abstract syntax tree library *(dependency of rope)*

- **toml** / **tomli** - TOML configuration parsing *(may be needed)*

- **pytoolconfig** - Tool configuration management *(evaluate necessity)*

- **appdirs** - Application directory paths *(evaluate necessity)*

- **snowballstemmer** - Text stemming *(used by pydocstyle, may remove)*

**Timeline: 2-3 weeks**

- [x] Create `pymode/ruff_integration.py`

- [x] Implement `run_ruff_check()` function

- [x] Implement `run_ruff_format()` function

- [x] Handle ruff subprocess execution and error parsing

- [x] Convert ruff JSON output to vim-compatible format

- [x] Map existing `g:pymode_lint_checkers` to ruff rule selection

- [x] Convert `g:pymode_lint_ignore` patterns to ruff ignore rules

- [x] Convert `g:pymode_lint_select` patterns to ruff select rules

- [x] Handle tool-specific options (mccabe complexity, etc.)

- [x] Create configuration validation

- [x] Update `pymode/lint.py` - replace pylama integration

- [x] Update `pymode/__init__.py` - replace autopep8 import

- [x] Update `autoload/pymode/lint.vim` - modify VimScript functions

- [x] Ensure async linting compatibility

- [x] Preserve error reporting format

**Timeline: 1 week**

- [ ] Remove from `.gitmodules`:

- `submodules/pyflakes`

- `submodules/pycodestyle`

- `submodules/mccabe`

- `submodules/pylint`

- `submodules/pydocstyle`

- `submodules/pylama`

- `submodules/autopep8`

- [ ] Clean up submodule references in git

- [ ] Update repository size documentation

- [ ] Add ruff as external dependency requirement

- [ ] Update installation documentation in README.md

- [ ] Modify `Dockerfile` and `Dockerfile.base` to include ruff

- [ ] Update `docker-compose.yml` if needed

- [ ] Create installation verification script

- [ ] Modify `pymode/utils.py` `patch_paths()` function

- [ ] Remove submodule path additions for replaced tools

- [ ] Keep paths for remaining tools (rope, toml, etc.)

- [ ] Test path resolution on different platforms

**Timeline: 1 week**

- [ ] Map current settings to ruff equivalents:

```

```

- [ ] Create configuration converter utility

- [ ] Document configuration changes

- [ ] Add ruff-specific VimScript options:

```vim

```

- [ ] Update default configurations

- [ ] Add configuration validation

**Timeline: 1 week**

- [ ] Maintain rope submodule

- [ ] Keep astroid dependency if required by rope

- [ ] Preserve all rope functionality:

- Code completion

- Go to definition

- Refactoring operations

- Auto-imports

- [ ] Test rope integration with new ruff setup

- [ ] Evaluate toml/tomli necessity for ruff config

- [ ] Assess pytoolconfig requirement

- [ ] Determine if appdirs is still needed

- [ ] Remove snowballstemmer if pydocstyle is replaced

- [ ] Update dependency documentation

**Timeline: 2-3 weeks**

- [ ] Modify `tests/test_bash/test_autopep8.sh` for ruff formatting

- [ ] Update `tests/test_procedures_vimscript/autopep8.vim`

- [ ] Create comprehensive ruff integration tests

- [ ] Test error handling and edge cases

- [ ] Ensure all existing functionality works

- [ ] Benchmark ruff vs. current tools

- [ ] Measure linting speed improvements

- [ ] Verify memory usage reduction

- [ ] Ensure async linting performance

- [ ] Test with large codebases

- [ ] Test with Python versions 3.10-3.13

- [ ] Verify Docker environment compatibility

- [ ] Test on Linux, macOS, Windows

- [ ] Test with different Vim/Neovim versions

- [ ] Validate plugin manager compatibility

**Timeline: 1-2 weeks**

- [ ] Update `doc/pymode.txt` with ruff information

- [ ] Create migration guide from old configuration

- [ ] Document new ruff-specific features

- [ ] Update README.md with new requirements

- [ ] Add troubleshooting section

- [ ] Create configuration converter script

- [ ] Implement backward compatibility warnings

- [ ] Document breaking changes clearly

- [ ] Provide rollback instructions

- [ ] Create migration validation script

- [ ] Plan release as major version (0.15.0)

- [ ] Prepare changelog with breaking changes

- [ ] Create upgrade documentation

- [ ] Consider maintaining compatibility branch

- [ ] Plan communication strategy

- **10-100x faster linting** compared to current tool combination

- **Reduced memory usage** by eliminating multiple tool processes

- **Single tool coordination** instead of managing multiple linters

- **Near-instantaneous feedback** for developers

- **7 fewer submodules** to maintain and update

- **Unified configuration** instead of multiple tool configs

- **Simplified dependency management**

- **Easier troubleshooting** with single tool

- **Faster development workflow**

- **Consistent linting behavior**

- **Modern linting rules and features**

- **Better error messages and suggestions**

| Risk | Impact | Probability | Mitigation |

|------|--------|-------------|------------|

| Configuration breaking changes | High | High | Provide migration tools and compatibility warnings |

| Performance regression in edge cases | Medium | Low | Comprehensive benchmarking and testing |

| Feature gaps vs. current tools | Medium | Medium | Document differences and provide alternatives |

| Risk | Impact | Probability | Mitigation |

|------|--------|-------------|------------|

| User adoption resistance | Medium | Medium | Clear communication of benefits and smooth migration |

| Integration issues with existing workflows | Medium | Low | Extensive compatibility testing |

| Ruff dependency management | Low | Low | Document installation requirements clearly |

- [ ] Linting speed improvement: Target 10x faster minimum

- [ ] Memory usage reduction: Target 50% reduction

- [ ] Plugin load time: No regression

- [ ] All existing tests pass

- [ ] No regression in error detection capability

- [ ] User configuration migration success rate >95%

- [ ] Documentation completeness score >90%

- [ ] User migration guide effectiveness

- [ ] Issue resolution time improvement

| Phase | Duration | Key Deliverables |

|-------|----------|------------------|

| Phase 1 | 2-3 weeks | Ruff integration module, core file updates |

| Phase 2 | 1 week | Submodule removal, build system updates |

| Phase 3 | 1 week | Configuration migration system |

| Phase 4 | 1 week | Advanced feature preservation |

| Phase 5 | 2-3 weeks | Comprehensive testing and validation |

| Phase 6 | 1-2 weeks | Documentation and release preparation |

| **Total** | **7-10 weeks** | **Full ruff migration complete** |

This migration plan will significantly modernize python-mode by replacing 7 legacy submodules with a single, fast, modern tool while preserving essential features like rope integration. The result will be a faster, more maintainable, and more user-friendly Python development environment in Vim.

The structured approach ensures minimal disruption to existing users while providing substantial performance and maintenance benefits. The comprehensive testing and documentation phases will ensure a smooth transition for the entire python-mode community.