405 lines
7.6 KiB
Markdown
405 lines
7.6 KiB
Markdown
# Codebase Exploration Notes: [Project Name]
|
|
|
|
**Repository:** [URL or path]
|
|
**Explored:** [date]
|
|
**For Issue:** #[number]
|
|
**Language:** [primary language]
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
**Essential Commands:**
|
|
```bash
|
|
# Install dependencies
|
|
[command]
|
|
|
|
# Run dev server
|
|
[command]
|
|
|
|
# Run tests
|
|
[command]
|
|
|
|
# Lint/format
|
|
[command]
|
|
```
|
|
|
|
**Key Directories:**
|
|
- Source: `[path]`
|
|
- Tests: `[path]`
|
|
- Docs: `[path]`
|
|
|
|
---
|
|
|
|
## Project Summary
|
|
|
|
[2-3 sentences about what this project does and how it's structured]
|
|
|
|
**Purpose:** [What problem does this solve?]
|
|
|
|
**Target Users:** [Developer tool / Web app / Library / CLI / etc]
|
|
|
|
**Core Technologies:**
|
|
- Language: [language + version]
|
|
- Framework: [if applicable]
|
|
- Build tool: [tool]
|
|
- Testing: [framework]
|
|
|
|
**Project Maturity:**
|
|
- Age: [years or months]
|
|
- Activity: [active / moderate / slow]
|
|
- Contributors: [approximate count]
|
|
- Stability: [alpha / beta / stable / mature]
|
|
|
|
---
|
|
|
|
## Directory Structure
|
|
|
|
```
|
|
project-root/
|
|
├── [main-source-dir]/ - [purpose]
|
|
├── [test-dir]/ - [purpose]
|
|
├── [docs-dir]/ - [purpose]
|
|
├── [config-files] - [purpose]
|
|
└── [other-key-dirs]/ - [purpose]
|
|
```
|
|
|
|
**Organization Principle:**
|
|
- [ ] By feature (users/, products/, orders/)
|
|
- [ ] By layer (models/, views/, controllers/)
|
|
- [ ] By type (components/, utils/, services/)
|
|
- [ ] Hybrid approach
|
|
|
|
**Notes:**
|
|
[Any special organization patterns or unusual directory purposes]
|
|
|
|
---
|
|
|
|
## Code Conventions
|
|
|
|
### Naming Conventions
|
|
|
|
**Files:**
|
|
- Pattern: [kebab-case / PascalCase / snake_case]
|
|
- Extensions: [.js, .ts, .tsx, etc]
|
|
- Tests: [*.test.js / *_test.go / test_*.py]
|
|
|
|
**Code Elements:**
|
|
- Classes: [PascalCase]
|
|
- Functions: [camelCase / snake_case]
|
|
- Variables: [camelCase / snake_case]
|
|
- Constants: [UPPER_SNAKE_CASE / kConstant]
|
|
- Private: [_private / #private / __private]
|
|
|
|
**Examples from codebase:**
|
|
```[language]
|
|
// Actual examples from the project
|
|
class ExampleClass { }
|
|
function exampleFunction() { }
|
|
const EXAMPLE_CONSTANT = 'value'
|
|
```
|
|
|
|
### Code Style
|
|
|
|
**Formatting:**
|
|
- Indentation: [2 spaces / 4 spaces / tabs]
|
|
- Line length: [80 / 100 / 120 chars]
|
|
- Quotes: [single / double]
|
|
- Semicolons: [required / optional]
|
|
|
|
**Imports:**
|
|
```[language]
|
|
// Import order example from project
|
|
import external from 'package'
|
|
import internal from '@/internal'
|
|
import relative from './relative'
|
|
```
|
|
|
|
**Comments:**
|
|
- Documentation: [JSDoc / docstrings / rustdoc / etc]
|
|
- Inline: [when and how used]
|
|
- TODO format: [TODO: / TODO(name): / FIXME:]
|
|
|
|
**Error Handling:**
|
|
- Pattern: [try/catch / Result<T,E> / error codes]
|
|
- Custom errors: [how defined]
|
|
- Error messages: [format and style]
|
|
|
|
### Architectural Patterns
|
|
|
|
**Overall Pattern:**
|
|
[MVC / MVVM / Layered / Component-based / etc]
|
|
|
|
**State Management:**
|
|
[How application state is managed]
|
|
|
|
**Data Flow:**
|
|
[How data moves through the system]
|
|
|
|
**Dependency Direction:**
|
|
[e.g., UI → Services → Data Layer]
|
|
|
|
**Key Abstractions:**
|
|
- [Abstraction 1]: [purpose and how used]
|
|
- [Abstraction 2]: [purpose and how used]
|
|
|
|
---
|
|
|
|
## Testing
|
|
|
|
### Test Framework & Location
|
|
|
|
**Framework:** [Jest / pytest / JUnit / etc]
|
|
|
|
**Test Locations:**
|
|
- Unit tests: [path pattern]
|
|
- Integration tests: [path pattern]
|
|
- E2E tests: [path pattern]
|
|
|
|
**Test Naming:**
|
|
- Pattern: [describe/it / test_ / Test* / #[test]]
|
|
- Convention: [naming style for test descriptions]
|
|
|
|
### Test Structure
|
|
|
|
**Typical test pattern:**
|
|
```[language]
|
|
// Example test structure from the project
|
|
describe('FeatureName', () => {
|
|
it('should do X when Y', () => {
|
|
// Arrange
|
|
// Act
|
|
// Assert
|
|
})
|
|
})
|
|
```
|
|
|
|
**Common patterns:**
|
|
- Setup/teardown: [how handled]
|
|
- Fixtures: [location and usage]
|
|
- Mocks: [how created]
|
|
- Assertions: [library and style]
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
# All tests
|
|
[command]
|
|
|
|
# Specific file
|
|
[command]
|
|
|
|
# With coverage
|
|
[command]
|
|
|
|
# Watch mode
|
|
[command]
|
|
```
|
|
|
|
**Coverage:**
|
|
- Target: [percentage if specified]
|
|
- Tool: [coverage tool used]
|
|
- Reports: [where generated]
|
|
|
|
---
|
|
|
|
## Development Workflow
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
# Initial setup
|
|
git clone [repo]
|
|
cd [project]
|
|
[install command]
|
|
[setup environment]
|
|
```
|
|
|
|
**Prerequisites:**
|
|
- [Tool/version requirement 1]
|
|
- [Tool/version requirement 2]
|
|
|
|
### Development Commands
|
|
|
|
```bash
|
|
# Development mode
|
|
[command]
|
|
|
|
# Build
|
|
[command]
|
|
|
|
# Lint
|
|
[command]
|
|
|
|
# Format
|
|
[command]
|
|
|
|
# Type check (if applicable)
|
|
[command]
|
|
```
|
|
|
|
### Git Workflow
|
|
|
|
**Branch naming:** [pattern: feature/*, fix/*, etc]
|
|
|
|
**Commit format:**
|
|
```
|
|
type(scope): description
|
|
|
|
[longer explanation if needed]
|
|
```
|
|
|
|
**Pre-commit hooks:**
|
|
- [What runs automatically]
|
|
|
|
---
|
|
|
|
## CI/CD
|
|
|
|
**CI System:** [GitHub Actions / Travis / CircleCI / etc]
|
|
|
|
**Configuration:** [.github/workflows/* / .travis.yml / etc]
|
|
|
|
**CI Checks:**
|
|
- [ ] Tests
|
|
- [ ] Linting
|
|
- [ ] Type checking
|
|
- [ ] Build
|
|
- [ ] Coverage
|
|
- [ ] [Other checks]
|
|
|
|
**Important:** [Any CI-specific considerations]
|
|
|
|
---
|
|
|
|
## Reference Examples
|
|
|
|
### For My Work
|
|
|
|
**Similar features/patterns:**
|
|
|
|
1. **[Feature/Pattern 1]**
|
|
- File: `[path/to/file]:[line]`
|
|
- What it does: [description]
|
|
- Why relevant: [how it relates to my issue]
|
|
- Pattern to follow: [specific pattern]
|
|
|
|
2. **[Feature/Pattern 2]**
|
|
- File: `[path/to/file]:[line]`
|
|
- What it does: [description]
|
|
- Why relevant: [how it relates]
|
|
- Pattern to follow: [specific pattern]
|
|
|
|
3. **[Feature/Pattern 3]**
|
|
- File: `[path/to/file]:[line]`
|
|
- What it does: [description]
|
|
- Why relevant: [how it relates]
|
|
|
|
### Patterns to Replicate
|
|
|
|
- **[Pattern 1]:** [e.g., how errors are handled]
|
|
- Example: [file:line]
|
|
- Apply to: [my use case]
|
|
|
|
- **[Pattern 2]:** [e.g., how validation is done]
|
|
- Example: [file:line]
|
|
- Apply to: [my use case]
|
|
|
|
- **[Pattern 3]:** [e.g., how tests are structured]
|
|
- Example: [file:line]
|
|
- Apply to: [my use case]
|
|
|
|
### Patterns to Avoid
|
|
|
|
- **[Anti-pattern 1]:** [old code being refactored]
|
|
- **[Anti-pattern 2]:** [special case, don't generalize]
|
|
|
|
---
|
|
|
|
## Impact Analysis
|
|
|
|
### Files I'll Likely Modify
|
|
|
|
1. **`[path/to/file1]`**
|
|
- Reason: [why this file]
|
|
- Change type: [add / modify / delete]
|
|
- Confidence: [high / medium / low]
|
|
|
|
2. **`[path/to/file2]`**
|
|
- Reason: [why this file]
|
|
- Change type: [add / modify / delete]
|
|
- Confidence: [high / medium / low]
|
|
|
|
### Dependencies to Consider
|
|
|
|
**Upstream (what calls my changes):**
|
|
- [Dependency 1]: [description]
|
|
- [Dependency 2]: [description]
|
|
|
|
**Downstream (what my changes call):**
|
|
- [Dependency 1]: [description]
|
|
- [Dependency 2]: [description]
|
|
|
|
**Side effects:**
|
|
- [ ] File I/O
|
|
- [ ] Network calls
|
|
- [ ] Database operations
|
|
- [ ] State mutations
|
|
- [ ] Event emissions
|
|
|
|
### Risk Level
|
|
|
|
**Overall risk:** 🟢 Low / 🟡 Medium / 🔴 High
|
|
|
|
**Risk factors:**
|
|
- [Factor 1: e.g., modifying critical path]
|
|
- [Factor 2: e.g., poorly tested area]
|
|
|
|
**Mitigation:**
|
|
- [Strategy 1: e.g., add extra tests]
|
|
- [Strategy 2: e.g., incremental changes]
|
|
|
|
---
|
|
|
|
## Notes & Questions
|
|
|
|
### Key Observations
|
|
|
|
- [Observation 1: interesting pattern or consideration]
|
|
- [Observation 2: something to remember]
|
|
- [Observation 3: potential challenge]
|
|
|
|
### Still Unclear
|
|
|
|
- [ ] [Question 1: what still needs investigation]
|
|
- [ ] [Question 2: clarification needed]
|
|
- [ ] [Question 3: uncertainty]
|
|
|
|
### Resources
|
|
|
|
- Documentation: [links to relevant docs]
|
|
- Similar issues: [links to related issues/PRs]
|
|
- References: [external resources]
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
✅ Exploration complete - Ready for **Phase 4: Issue-Code Mapping**
|
|
|
|
**Recommended focus:**
|
|
1. [Specific file/component to examine more closely]
|
|
2. [Pattern to understand deeper]
|
|
3. [Test to review as reference]
|
|
|
|
**Action items:**
|
|
- [ ] [Specific exploration task if needed]
|
|
- [ ] [Question to ask maintainer if needed]
|
|
- [ ] [Code to trace if needed]
|
|
|
|
---
|
|
|
|
## Personal Notes
|
|
|
|
[Any additional thoughts, reminders, or insights for myself]
|