142 lines
4.7 KiB
Markdown
142 lines
4.7 KiB
Markdown
# 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)
|