BMAD-METHOD/expansion-packs/bmad-technical-writing/checklists/repository-quality-checklist.md

Repository Quality Checklist

Use this checklist to ensure your code repository is professional, organized, and user-friendly.

Repository Basics

• Clear README.md in root directory
• Repository name descriptive and professional
• Description accurate in repository settings
• Topics/tags added for discoverability
• Repository is public (unless there's a reason for private)

README.md Quality

• Title clearly states repository purpose
• "About This Repository" section explains context
• Prerequisites listed explicitly
• Installation instructions step-by-step
• Usage examples provided
• Links to book or related resources
• Repository structure explained
• Contact/support information included

Folder Structure

• Logical organization (by chapter, topic, or feature)
• Consistent naming conventions (chapter-01, ch01, or 01-chapter-name)
• Each chapter/section has its own folder
• Separate folders for tests, docs, images (if applicable)
• No cluttered root directory

Code Quality

• All code follows language-specific style guide
• Code is well-commented
• No commented-out code left in repository
• No debugging print statements left in code
• Code examples are self-contained and runnable
• Each example includes necessary imports/dependencies

Dependencies

• Requirements file present (requirements.txt, package.json, Gemfile, etc.)
• Dependencies pinned to specific versions
• No unnecessary dependencies
• Instructions for installing dependencies in README
• Separate dev dependencies if applicable

Documentation

• Each chapter folder has its own README (optional but helpful)
• Code examples explained in comments or accompanying markdown
• Expected output documented
• Common issues/troubleshooting noted
• API documentation if applicable

Testing

• Unit tests included (if appropriate)
• Test instructions in README
• Tests pass before committing
• CI/CD set up to run tests automatically (optional)
• Test coverage reasonable for educational repository

Git Hygiene

• .gitignore appropriate for language/framework
• No sensitive data committed (API keys, passwords, credentials)
• No large binary files (unless necessary)
• No IDE-specific files (.vscode/, .idea/ ignored)
• No OS-specific files (.DS_Store, Thumbs.db ignored)
• Commit messages are descriptive
• No merge conflict markers in code

Licensing

• LICENSE file present
• License appropriate for educational code (MIT, Apache 2.0 common)
• License year and copyright holder correct
• License compatible with book's license

Cross-Platform Support

• Code works on Windows, macOS, Linux (as applicable)
• File paths use cross-platform methods
• Installation instructions for all platforms
• Platform-specific issues documented

Accessibility

• Code examples run out-of-the-box (no complex setup)
• Error messages are helpful
• Installation doesn't require expensive tools
• Alternative approaches provided if dependencies are heavy

GitHub/GitLab Features

• Repository topics/tags set
• Issues enabled (if accepting feedback)
• Discussions enabled (if building community)
• Security policy (SECURITY.md) if applicable
• Contributing guidelines (CONTRIBUTING.md) if accepting PRs

CI/CD (Optional but Recommended)

• GitHub Actions or equivalent set up
• Tests run automatically on push/PR
• Linting checks automated
• Build status badge in README
• Multi-platform testing (if applicable)

Release Management

• Tagged releases for book versions (v1.0, v2.0, etc.)
• Release notes describing changes
• Stable branch for published version
• Development branch for updates (if applicable)

Reader Experience

• Clone and run test: can a reader clone and run immediately?
• Instructions are clear to someone unfamiliar with the repository
• No "works on my machine" problems
• Examples produce expected output
• Repository organized logically from reader's perspective

Maintenance

• Dependencies not outdated (security vulnerabilities)
• Deprecated features noted
• Updates planned for major language/framework changes
• Errata or known issues documented
• Responsive to issues and questions (if accepting them)

Integration with Book

• Repository linked prominently in book's front matter
• Repository URL easy to type (short, memorable)
• Chapter code maps clearly to book chapters
• Repository supports book's learning objectives
• Code in repository matches code in book (or noted if intentionally different)