@@ -31,6 +31,9 @@ uv run pytest tests/test_cli.py::test_sync
31
31
uv run ptw .
32
32
# or
33
33
make start
34
+
35
+ # Run tests with coverage
36
+ uv run py.test --cov -v
34
37
```
35
38
36
39
#### Code Quality
@@ -41,8 +44,8 @@ uv run ruff format .
41
44
# or
42
45
make ruff_format
43
46
44
- # Run ruff linting
45
- uv run ruff check .
47
+ # Run ruff linting with auto-fixes
48
+ uv run ruff check . --fix --show-fixes
46
49
# or
47
50
make ruff
48
51
@@ -66,6 +69,16 @@ make build_docs
66
69
make start_docs
67
70
```
68
71
72
+ ## Development Process
73
+
74
+ Follow this workflow for code changes:
75
+
76
+ 1 . ** Format First** : ` uv run ruff format . `
77
+ 2 . ** Run Tests** : ` uv run py.test `
78
+ 3 . ** Run Linting** : ` uv run ruff check . --fix --show-fixes `
79
+ 4 . ** Check Types** : ` uv run mypy `
80
+ 5 . ** Verify Tests Again** : ` uv run py.test `
81
+
69
82
## Code Architecture
70
83
71
84
### Core Components
@@ -98,21 +111,128 @@ Example format:
98
111
awesome : " git+git://git.naquadah.org/awesome.git"
99
112
` ` `
100
113
114
+ ## Coding Standards
115
+
116
+ ### Imports
117
+
118
+ - Use namespace imports: ` import enum` instead of `from enum import Enum`
119
+ - For typing, use `import typing as t` and access via namespace : ` t.NamedTuple` , etc.
120
+ - Use `from __future__ import annotations` at the top of all Python files
121
+
122
+ # ## Docstrings
123
+
124
+ Follow NumPy docstring style for all functions and methods :
125
+
126
+ ` ` ` python
127
+ """Short description of the function or class.
128
+
129
+ Detailed description using reStructuredText format.
130
+
131
+ Parameters
132
+ ----------
133
+ param1 : type
134
+ Description of param1
135
+ param2 : type
136
+ Description of param2
137
+
138
+ Returns
139
+ -------
140
+ type
141
+ Description of return value
142
+ """
143
+ ` ` `
144
+
101
145
# ## Testing
102
146
103
- Tests use pytest and are organized by component functionality:
104
- - ` tests/test_cli.py`: Tests for CLI functionality
105
- - `tests/test_config.py` : Tests for configuration parsing
106
- - `tests/test_sync.py` : Tests for repository synchronization
147
+ # ### Using libvcs Fixtures
148
+
149
+ When writing tests, leverage libvcs's pytest plugin fixtures :
150
+
151
+ - `create_git_remote_repo`, `create_svn_remote_repo`, `create_hg_remote_repo` : Factory fixtures
152
+ - `git_repo`, `svn_repo`, `hg_repo` : Pre-made repository instances
153
+ - `set_home`, `gitconfig`, `hgconfig`, `git_commit_envvars` : Environment fixtures
154
+
155
+ Example :
156
+ ` ` ` python
157
+ def test_vcspull_sync(git_repo):
158
+ # git_repo is already a GitSync instance with a clean repository
159
+ # Use it directly in your tests
160
+ ` ` `
161
+
162
+ # ### Test Structure
163
+
164
+ Use `typing.NamedTuple` for parameterized tests :
165
+
166
+ ` ` ` python
167
+ class SyncFixture(t.NamedTuple):
168
+ test_id: str # For test naming
169
+ sync_args: list[str]
170
+ expected_exit_code: int
171
+ expected_in_out: ExpectedOutput = None
172
+
173
+ @pytest.mark.parametrize(
174
+ list(SyncFixture._fields),
175
+ SYNC_REPO_FIXTURES,
176
+ ids=[test.test_id for test in SYNC_REPO_FIXTURES],
177
+ )
178
+ def test_sync(
179
+ # Parameters and fixtures...
180
+ ):
181
+ # Test implementation
182
+ ` ` `
183
+
184
+ # ### Mocking Strategy
185
+
186
+ - Use `monkeypatch` for environment, globals, attributes
187
+ - Use `mocker` (from pytest-mock) for application code
188
+ - Document every mock with comments explaining WHAT is being mocked and WHY
107
189
108
- # # Best Practices
190
+ # ### Configuration File Testing
191
+
192
+ - Use project helper functions like `vcspull.tests.helpers.write_config` or `save_config_yaml`
193
+ - Avoid direct `yaml.dump` or `file.write_text` for config creation
194
+
195
+ # ## Git Commit Standards
196
+
197
+ Format commit messages as :
198
+ ` ` `
199
+ Component/File(commit-type[Subcomponent/method]): Concise description
109
200
110
- 1. **Types** : The codebase uses strict typing with mypy. All new code should include proper type annotations.
201
+ why: Explanation of necessity or impact.
202
+ what:
203
+ - Specific technical changes made
204
+ - Focused on a single topic
205
+
206
+ refs: #issue-number, breaking changes, or relevant links
207
+ ` ` `
208
+
209
+ Common commit types :
210
+ - **feat**: New features or enhancements
211
+ - **fix**: Bug fixes
212
+ - **refactor**: Code restructuring without functional change
213
+ - **docs**: Documentation updates
214
+ - **chore**: Maintenance (dependencies, tooling, config)
215
+ - **test**: Test-related updates
216
+ - **style**: Code style and formatting
217
+
218
+ Example :
219
+ ` ` `
220
+ cli/add(feat[add_repo]): Add support for custom remote URLs
221
+
222
+ why: Enable users to specify alternative remote URLs for repositories
223
+ what:
224
+ - Add remote_url parameter to add_repo function
225
+ - Update CLI argument parser to accept --remote-url option
226
+ - Add tests for the new functionality
227
+
228
+ refs: #123
229
+ ` ` `
111
230
112
- 2. **Docstrings** : The project follows NumPy docstring style for all functions and methods.
231
+ # # Debugging Tips
113
232
114
- 3. **Error Handling** : Exceptions are defined in `exc.py`. Use appropriate exception types.
233
+ When stuck in debugging loops :
115
234
116
- 4. **Testing Approach** :
117
- - Tests use fixtures extensively (see `conftest.py` and `tests/fixtures/`)
118
- - CLI tests use parameter fixtures with clear IDs for readability
235
+ 1. **Pause and acknowledge the loop**
236
+ 2. **Minimize to MVP** : Remove all debugging cruft and experimental code
237
+ 3. **Document the issue** comprehensively for a fresh approach
238
+ 4. Format for portability (using quadruple backticks)
0 commit comments