zhongwei/gh-devkade-collaborator-skills-oss-contribution-framework
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2359544dbc2b44a2c092ebf42669fdc2de1acb55
gh-devkade-collaborator-ski…/references/codebase-checklist.md
Zhongwei Li 2359544dbc Initial commit
2025-11-29 18:19:43 +08:00

12 KiB
Raw Blame History

Codebase Exploration Checklist

Systematic checklist for understanding a new codebase.

Initial Overview

Documentation Review

  • Read README.md thoroughly
  • Review CONTRIBUTING.md for guidelines
  • Check ARCHITECTURE.md or design docs
  • Read recent CHANGELOG entries
  • Review LICENSE and any legal requirements
  • Check CODE_OF_CONDUCT.md
  • Read SECURITY.md for vulnerability reporting

Project Metadata

  • Identify project purpose and scope
  • Understand target users/audience
  • Note primary programming language(s)
  • Check framework/platform used
  • Identify project maturity (alpha/beta/stable)
  • Review release cadence
  • Check activity level (recent commits)

Repository Structure

Directory Mapping

  • Identify main source directory (src/, lib/, app/)
  • Locate test directory (test/, tests/, tests/)
  • Find documentation (docs/, doc/)
  • Identify build output (dist/, build/, target/)
  • Locate configuration files (config/, .config/)
  • Find examples/samples (examples/, samples/)
  • Check for scripts (scripts/, tools/, bin/)

Organization Pattern

  • Determine organization principle:
    • By feature (user/, product/, order/)
    • By layer (models/, views/, controllers/)
    • By type (components/, utils/, services/)
    • Hybrid approach
  • Note any special directories
  • Understand separation of concerns
  • Identify public vs internal code

Build System & Dependencies

Package Management

  • Identify package manager (npm, yarn, pip, cargo, maven)
  • Locate package manifest (package.json, requirements.txt, Cargo.toml)
  • Review dependencies and their purposes
  • Check for peer dependencies
  • Note any unusual or unfamiliar dependencies
  • Check dependency versions and compatibility

Build Configuration

  • Identify build tool (webpack, vite, rollup, gradle)
  • Locate build configuration files
  • Understand build process
  • Check for multiple build targets (dev, prod)
  • Note output artifacts
  • Identify entry points

Setup & Installation

  • Follow setup instructions in README
  • Install dependencies successfully
  • Verify development environment works
  • Run development server/app
  • Check for environment variable requirements
  • Note any platform-specific setup

Code Conventions

Naming Conventions

  • File naming pattern:
    • kebab-case, PascalCase, snake_case, camelCase
    • Extensions used (.ts, .tsx, .js, .jsx, .py, .rs)
  • Directory naming pattern
  • Component/class naming (PascalCase, etc)
  • Function/method naming (camelCase, snake_case)
  • Variable naming (camelCase, snake_case)
  • Constant naming (UPPER_SNAKE_CASE, kConstant)
  • Private member naming (_private, #private, __private)
  • Boolean naming (isX, hasY, shouldZ)

Code Style

  • Indentation (tabs vs spaces, size)
  • Line length limit
  • Quote style (single, double)
  • Semicolon usage
  • Brace style (same line, new line)
  • Import organization and ordering
  • Blank line conventions
  • Trailing comma usage

Formatting Tools

  • Check for .editorconfig
  • Look for .prettierrc or prettier.config.js
  • Check for .eslintrc or eslint.config.js
  • Find other linter configs (.pylintrc, rustfmt.toml)
  • Run formatter to see changes
  • Run linter to check compliance

Testing

Test Framework

  • Identify testing framework (Jest, pytest, JUnit, etc)
  • Locate test configuration
  • Understand test file naming convention
  • Check test location pattern (co-located vs separate)
  • Note test file extensions

Test Structure

  • Identify test structure pattern:
    • describe/it (Jest, Mocha)
    • test_ prefix (pytest)
    • Test* classes (JUnit)
    • #[test] attributes (Rust)
  • Check for test helpers/utilities
  • Review fixture patterns
  • Understand mocking approach
  • Note setup/teardown patterns

Test Commands

  • Run all tests: [command]
  • Run specific test file: [command]
  • Run with coverage: [command]
  • Run in watch mode: [command]
  • Run integration tests: [command]
  • Run e2e tests: [command]

Test Coverage

  • Check coverage tool (nyc, coverage.py, tarpaulin)
  • Find coverage configuration
  • Identify coverage thresholds
  • Locate coverage reports
  • Check what's excluded from coverage

Test Patterns

  • Review 3-5 existing tests
  • Identify assertion library/style
  • Understand test data approach
  • Note how mocks are created
  • Check async test patterns
  • Review error/exception testing
  • Understand snapshot testing (if used)

Development Workflow

Running Locally

  • Start development server: [command]
  • Build for development: [command]
  • Build for production: [command]
  • Watch mode: [command]
  • Clean build: [command]

Code Quality

  • Lint code: [command]
  • Fix linting issues: [command]
  • Format code: [command]
  • Type check (if applicable): [command]
  • Run pre-commit checks: [command]

Git Workflow

  • Check branching strategy (git flow, trunk-based)
  • Understand branch naming convention
  • Review commit message format
  • Check for commit hooks (husky, pre-commit)
  • Note PR/merge requirements
  • Understand rebase vs merge policy

CI/CD

Continuous Integration

  • Identify CI system (GitHub Actions, Travis, CircleCI)
  • Locate CI configuration (.github/workflows/, .travis.yml)
  • Review CI jobs/pipelines
  • Understand what CI checks:
    • Tests
    • Linting
    • Type checking
    • Build
    • Coverage
    • Security scanning
  • Note CI environment differences
  • Check if CI runs on all branches or just some

Deployment

  • Check deployment process
  • Identify deployment targets (npm, docker, cloud)
  • Review deployment configuration
  • Understand release process
  • Note versioning strategy (semver, calver)

Architecture & Patterns

Overall Architecture

  • Identify architectural pattern:
    • MVC/MVP/MVVM
    • Layered
    • Clean Architecture
    • Microservices
    • Monolithic
    • Component-based
  • Understand data flow
  • Identify key abstractions
  • Note separation of concerns
  • Check dependency direction

Design Patterns

  • Identify common design patterns used:
    • Factory
    • Strategy
    • Observer
    • Decorator
    • Adapter
    • Singleton
    • Repository
    • Service
  • Note framework-specific patterns
  • Understand composition patterns

State Management (if applicable)

  • Identify state management approach:
    • Redux/Zustand/MobX
    • Context API
    • Local state
    • Server state (React Query, SWR)
  • Understand state organization
  • Note where state lives
  • Check for state persistence

API/Interface Patterns

  • Identify API style (REST, GraphQL, gRPC)
  • Understand error handling pattern
  • Note validation approach
  • Check authentication/authorization pattern
  • Review data serialization

Language/Framework Specifics

JavaScript/TypeScript

  • Check ES version target
  • Note module system (ESM, CommonJS)
  • Review TypeScript config (if TS)
  • Check for type definitions
  • Note async patterns (Promise, async/await)
  • Review bundler configuration

Python

  • Check Python version
  • Note import style (absolute vs relative)
  • Review requirements/dependencies
  • Check for virtual environment usage
  • Note async patterns (asyncio, threading)
  • Review packaging configuration (setup.py, pyproject.toml)

Rust

  • Check Rust edition
  • Review Cargo.toml features
  • Note error handling pattern (Result, panic)
  • Check for unsafe code usage
  • Review trait usage patterns
  • Note lifetime annotation style

Go

  • Check Go version
  • Review module dependencies (go.mod)
  • Note package organization
  • Check error handling pattern
  • Review interface usage
  • Note concurrency patterns (goroutines, channels)

Finding Similar Code

Reference Examples

  • Find examples of similar features
  • Locate comparable components
  • Identify similar bug fixes
  • Review similar tests
  • Check similar API endpoints
  • Find analogous utilities

Search Strategies

# Find similar files
find . -name "*[similar-name]*"

# Find similar patterns
rg "pattern" --type [lang]

# Find similar classes/functions
rg "class.*Name|function.*Name"

# Find usages
rg "functionName\("

# Find similar tests
rg "test.*similar|describe.*Similar"

Code Reading

Entry Points

  • Identify main entry point (main.js, main.py, main.rs)
  • Find route definitions (for web apps)
  • Locate command definitions (for CLI tools)
  • Identify public API (for libraries)
  • Find initialization code

Core Components

  • Identify 3-5 most important modules
  • Understand their responsibilities
  • Note their relationships
  • Review their interfaces
  • Check their dependencies

Code Flow

  • Trace a simple user action
  • Follow a typical request path
  • Understand data transformations
  • Note side effects
  • Identify external calls

Documentation

Inline Documentation

  • Check documentation style (JSDoc, docstrings, rustdoc)
  • Review documentation coverage
  • Note documentation patterns
  • Check for examples in docs
  • Review parameter documentation

External Documentation

  • Check for API documentation
  • Review user guides
  • Find developer guides
  • Look for architecture diagrams
  • Check for decision records (ADRs)

Security & Performance

Security Practices

  • Check input validation patterns
  • Review authentication approach
  • Understand authorization checks
  • Note data sanitization
  • Check for security warnings in dependencies
  • Review secrets management

Performance Considerations

  • Identify performance-critical paths
  • Check for caching strategies
  • Note optimization patterns
  • Review resource management
  • Check for profiling tools

Community & Contribution

Communication Channels

  • Find discussion forum/Discord/Slack
  • Locate issue tracker
  • Check for mailing list
  • Find meeting notes (if any)
  • Review RFCs or proposals

Contribution Process

  • Review issue labels and meanings
  • Understand PR template requirements
  • Check review process
  • Note testing requirements
  • Understand merge criteria

Project-Specific Notes

Custom Conventions

  • Note any unusual patterns
  • Document project-specific terms
  • Record special requirements
  • Note gotchas or common mistakes
  • List helpful resources

Tool-Specific Setup

  • IDE/editor configuration
  • Debugging setup
  • Testing utilities
  • Code generation tools
  • Development aids

Completion Checklist

Before considering exploration complete:

  • Can navigate the codebase confidently
  • Understand main architecture and patterns
  • Know where to find things
  • Can run, build, and test locally
  • Understand contribution workflow
  • Have found reference examples
  • Know project conventions
  • Can ask informed questions
  • Ready to start implementation

Notes Template

Use this to record your findings:

# Codebase Exploration Notes: [Project Name]

**Date:** [date]
**For Issue:** #[number]

## Quick Reference
- Main language: [language]
- Framework: [framework]
- Test command: [command]
- Dev server: [command]

## Structure
[Key directory map]

## Conventions
[Important patterns to follow]

## Similar Code
[Reference examples for my work]

## Questions
[Things still unclear]

## Ready to Code
[Specific files/functions I'll modify]
Reference in New Issue View Git Blame Copy Permalink