|
| 1 | +# Development Guidelines |
| 2 | + |
| 3 | +This document contains critical information about working with this codebase. Follow these guidelines precisely. |
| 4 | + |
| 5 | +## Core Development Rules |
| 6 | + |
| 7 | +1. Package Management |
| 8 | + - ONLY use uv, NEVER pip |
| 9 | + - Installation: `uv add package` |
| 10 | + - Running tools: `uv run tool` |
| 11 | + - Upgrading: `uv add --dev package --upgrade-package package` |
| 12 | + - FORBIDDEN: `uv pip install`, `@latest` syntax |
| 13 | + |
| 14 | +2. Code Quality |
| 15 | + - Type hints required for all code |
| 16 | + - Public APIs must have docstrings |
| 17 | + - Functions must be focused and small |
| 18 | + - Follow existing patterns exactly |
| 19 | + - Line length: 88 chars maximum |
| 20 | + |
| 21 | +3. Testing Requirements |
| 22 | + - Framework: `uv run pytest` |
| 23 | + - Async testing: use anyio, not asyncio |
| 24 | + - Coverage: test edge cases and errors |
| 25 | + - New features require tests |
| 26 | + - Bug fixes require regression tests |
| 27 | + |
| 28 | +4. Code Style |
| 29 | + - PEP 8 naming (snake_case for functions/variables) |
| 30 | + - Class names in PascalCase |
| 31 | + - Constants in UPPER_SNAKE_CASE |
| 32 | + - Document with docstrings |
| 33 | + - Use f-strings for formatting |
| 34 | + |
| 35 | +- For commits fixing bugs or adding features based on user reports add: |
| 36 | + ```bash |
| 37 | + git commit --trailer "Reported-by:<name>" |
| 38 | + ``` |
| 39 | + Where `<name>` is the name of the user. |
| 40 | + |
| 41 | +- For commits related to a Github issue, add |
| 42 | + ```bash |
| 43 | + git commit --trailer "Github-Issue:#<number>" |
| 44 | + ``` |
| 45 | +- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never |
| 46 | + mention the tool used to create the commit message or PR. |
| 47 | + |
| 48 | +## Development Philosophy |
| 49 | + |
| 50 | +- **Simplicity**: Write simple, straightforward code |
| 51 | +- **Readability**: Make code easy to understand |
| 52 | +- **Performance**: Consider performance without sacrificing readability |
| 53 | +- **Maintainability**: Write code that's easy to update |
| 54 | +- **Testability**: Ensure code is testable |
| 55 | +- **Reusability**: Create reusable components and functions |
| 56 | +- **Less Code = Less Debt**: Minimize code footprint |
| 57 | + |
| 58 | +## Coding Best Practices |
| 59 | + |
| 60 | +- **Early Returns**: Use to avoid nested conditions |
| 61 | +- **Descriptive Names**: Use clear variable/function names (prefix handlers with "handle") |
| 62 | +- **Constants Over Functions**: Use constants where possible |
| 63 | +- **DRY Code**: Don't repeat yourself |
| 64 | +- **Functional Style**: Prefer functional, immutable approaches when not verbose |
| 65 | +- **Minimal Changes**: Only modify code related to the task at hand |
| 66 | +- **Function Ordering**: Define composing functions before their components |
| 67 | +- **TODO Comments**: Mark issues in existing code with "TODO:" prefix |
| 68 | +- **Simplicity**: Prioritize simplicity and readability over clever solutions |
| 69 | +- **Build Iteratively** Start with minimal functionality and verify it works before adding complexity |
| 70 | +- **Run Tests**: Test your code frequently with realistic inputs and validate outputs |
| 71 | +- **Build Test Environments**: Create testing environments for components that are difficult to validate directly |
| 72 | +- **Functional Code**: Use functional and stateless approaches where they improve clarity |
| 73 | +- **Clean logic**: Keep core logic clean and push implementation details to the edges |
| 74 | +- **File Organsiation**: Balance file organization with simplicity - use an appropriate number of files for the project scale |
| 75 | + |
| 76 | + |
| 77 | +## Core Components |
| 78 | + |
| 79 | +- `__main__.py`: Main entry point |
| 80 | +- `api`: API for the project |
| 81 | +- `tasks`: Tasks for the project |
| 82 | +- `models`: Models for the project |
| 83 | +- `loggers`: Loggers for the project |
| 84 | +- `utils`: Utility functions for the project |
| 85 | +- `tests`: Tests for the project |
| 86 | +- `configs`: Configs for the project |
| 87 | +- `data`: Data for the project |
| 88 | + |
| 89 | +Launch Command: |
| 90 | + |
| 91 | +```bash |
| 92 | +python -m lmms_eval --model qwen2_5_vl --model_args pretrained=Qwen/Qwen2.5-VL-3B-Instruct,max_pixels=12845056,attn_implementation=sdpa --tasks mmmu,mme,mmlu_flan_n_shot_generative --batch_size 128 --limit 8 --device cuda:0 |
| 93 | +``` |
| 94 | + |
| 95 | + |
| 96 | + |
| 97 | + |
| 98 | +## Pull Requests |
| 99 | + |
| 100 | +- Create a detailed message of what changed. Focus on the high level description of |
| 101 | + the problem it tries to solve, and how it is solved. Don't go into the specifics of the |
| 102 | + code unless it adds clarity. |
| 103 | + |
| 104 | +- NEVER ever mention a `co-authored-by` or similar aspects. In particular, never |
| 105 | + mention the tool used to create the commit message or PR. |
| 106 | + |
| 107 | +## Python Tools |
| 108 | + |
| 109 | +## Code Formatting |
| 110 | + |
| 111 | +1. Ruff |
| 112 | + - Format: `uv run ruff format .` |
| 113 | + - Check: `uv run ruff check .` |
| 114 | + - Fix: `uv run ruff check . --fix` |
| 115 | + - Critical issues: |
| 116 | + - Line length (88 chars) |
| 117 | + - Import sorting (I001) |
| 118 | + - Unused imports |
| 119 | + - Line wrapping: |
| 120 | + - Strings: use parentheses |
| 121 | + - Function calls: multi-line with proper indent |
| 122 | + - Imports: split into multiple lines |
| 123 | + |
| 124 | +2. Type Checking |
| 125 | + - Tool: `uv run pyright` |
| 126 | + - Requirements: |
| 127 | + - Explicit None checks for Optional |
| 128 | + - Type narrowing for strings |
| 129 | + - Version warnings can be ignored if checks pass |
| 130 | + |
| 131 | +3. Pre-commit |
| 132 | + - Config: `.pre-commit-config.yaml` |
| 133 | + - Runs: on git commit |
| 134 | + - Tools: Prettier (YAML/JSON), Ruff (Python) |
| 135 | + - Ruff updates: |
| 136 | + - Check PyPI versions |
| 137 | + - Update config rev |
| 138 | + - Commit config first |
| 139 | + |
| 140 | +## Error Resolution |
| 141 | + |
| 142 | +1. CI Failures |
| 143 | + - Fix order: |
| 144 | + 1. Formatting |
| 145 | + 2. Type errors |
| 146 | + 3. Linting |
| 147 | + - Type errors: |
| 148 | + - Get full line context |
| 149 | + - Check Optional types |
| 150 | + - Add type narrowing |
| 151 | + - Verify function signatures |
| 152 | + |
| 153 | +2. Common Issues |
| 154 | + - Line length: |
| 155 | + - Break strings with parentheses |
| 156 | + - Multi-line function calls |
| 157 | + - Split imports |
| 158 | + - Types: |
| 159 | + - Add None checks |
| 160 | + - Narrow string types |
| 161 | + - Match existing patterns |
| 162 | + |
| 163 | +3. Best Practices |
| 164 | + - Check git status before commits |
| 165 | + - Run formatters before type checks |
| 166 | + - Keep changes minimal |
| 167 | + - Follow existing patterns |
| 168 | + - Document public APIs |
| 169 | + - Test thoroughly |
0 commit comments