Initial commit
This commit is contained in:
Zhongwei Li
404
assets/templates/codebase-notes-template.md
Normal file
404
assets/templates/codebase-notes-template.md
Normal file
@@ -0,0 +1,404 @@
|
||||
# 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]
|
||||
Reference in New Issue
Block a user