You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
**Important**: Sorbet's autocorrect feature (`-a` flag) should be used cautiously as it can cause more issues than it resolves. Only use autocorrect when you have high confidence that the changes will not break code functionality.
162
+
**Important**: Sorbet's autocorrect feature (`-a` flag) should be used cautiously as it can cause more issues than it resolves. Only use autocorrect when you have high confidence that the changes will not break code functionality.
163
163
164
164
Autocorrect can handle some simple cases like:
165
-
- Adding missing `override.` annotations for method overrides
165
+
- Adding missing `override.` annotations for method overrides
166
166
- Adding `T.let` declarations for instance variables in strict-typed files
167
167
- Adding type annotations for constants
168
168
169
169
However, autocorrect often creates incorrect fixes for complex type mismatches, method signature issues, and structural problems. **Always manually resolve Sorbet errors** rather than relying on autocorrect, and carefully review any autocorrected changes to ensure they maintain code correctness and intent.
170
170
171
+
### Code Comments and Documentation
172
+
173
+
**Prioritize self-documenting code over comments**. Write clear, intention-revealing code with descriptive method and variable names that eliminate the need for explanatory comments.
174
+
175
+
**When to use comments**:
176
+
-**Business logic context**: Explain *why* something is done when the reason isn't obvious from the code
177
+
-**Complex algorithms**: Document the approach or mathematical concepts
178
+
-**Workarounds**: Explain why a non-obvious solution was necessary
179
+
-**External constraints**: Document API limitations, system requirements, or ecosystem-specific behaviors
180
+
-**TODO/FIXME**: Temporary markers for future improvements (with issue references when possible)
181
+
182
+
**Avoid these comment types**:
183
+
-**Implementation decisions**: Don't explain what was *not* implemented or alternative approaches considered
184
+
-**Obvious code explanations**: Don't restate what the code clearly does
-**Outdated information**: Remove comments that no longer apply to current implementation
187
+
-**Version history**: Use git history instead of inline change logs
188
+
189
+
**Comment style guidelines**:
190
+
```ruby
191
+
# Good: Explains WHY, adds business context
192
+
# Retry failed requests up to 3 times due to GitHub API rate limiting
193
+
retry_count =3
194
+
195
+
# Bad: Explains WHAT the code does (obvious from code)
196
+
# Set retry count to 3
197
+
retry_count =3
198
+
199
+
# Good: Documents external constraint
200
+
# GitHub API requires User-Agent header or returns 403
201
+
headers['User-Agent'] ='Dependabot/1.0'
202
+
203
+
# Bad: Implementation decision discussion
204
+
# We decided not to cache this because it would complicate the code
205
+
# and other ecosystems don't do caching here either
206
+
response = fetch_data(url)
207
+
```
208
+
209
+
**Prefer code refactoring over explanatory comments**:
210
+
```ruby
211
+
# Instead of commenting complex logic:
212
+
# Calculate the SHA256 of downloaded file for security verification
213
+
digest =Digest::SHA256.hexdigest(response.body)
214
+
215
+
# Extract to a well-named method:
216
+
defcalculate_security_checksum(content)
217
+
Digest::SHA256.hexdigest(content)
218
+
end
219
+
```
220
+
171
221
### Native Helpers
172
222
173
223
Many ecosystems use native language helpers (Go, Node.js, Python) located in `{ecosystem}/helpers/`. These helpers run exclusively within containers and changes require rebuilding:
When implementing new ecosystems or modifying existing ones, always ensure the 7 core classes are implemented and follow the established inheritance patterns from `dependabot-common`.
265
315
316
+
## Core Class Structure Pattern
317
+
318
+
**CRITICAL**: All Dependabot core classes with nested helper classes must follow the exact pattern to avoid "superclass mismatch" errors. This pattern is used consistently across all established ecosystems (bundler, npm_and_yarn, go_modules, etc.).
319
+
320
+
### Main Class Structure (applies to FileFetcher, FileParser, FileUpdater, UpdateChecker, etc.)
1.**Main classes** inherit from appropriate base: `Dependabot::FileUpdaters::Base`, `Dependabot::FileFetchers::Base`, etc.
358
+
2.**Helper classes** are nested inside the main class
359
+
3.**require_relative** statements go INSIDE the main class, not at module level
360
+
4.**Helper classes require the main file** first: `require "dependabot/{ecosystem}/file_updater"`
361
+
5.**Never define multiple top-level classes** with same name in the same namespace
362
+
6.**Backward compatibility** can use static methods that delegate to instance methods
363
+
364
+
### Applies To:
365
+
-**FileFetcher** and its helpers (e.g., `FileFetcher::GitCommitChecker`)
366
+
-**FileParser** and its helpers (e.g., `FileParser::ManifestParser`)
367
+
-**FileUpdater** and its helpers (e.g., `FileUpdater::LockfileUpdater`)
368
+
-**UpdateChecker** and its helpers (e.g., `UpdateChecker::VersionResolver`)
369
+
-**MetadataFinder** and its helpers
370
+
-**Version** and **Requirement** classes (if they have nested classes)
371
+
266
372
## Adding New Ecosystems
267
373
268
374
If you are adding a new ecosystem, follow the detailed guide in `./NEW_ECOSYSTEMS.md` which provides step-by-step instructions for implementing a new package manager ecosystem.
0 commit comments