Open source readiness checklist

[py-bay]

Development Repository README Checklist

Use this checklist for any development-oriented repository to ensure open source readiness.

✅ Essential Sections

Header

• Project title - Clear, descriptive name
• Tagline/Description - One sentence explaining what it does
• Badges
  • License
  • Build/CI status
  • Version/release
  • Code coverage (if available)
  • Language/framework version

Overview

• What problem does this solve? - Clear value proposition
• Key features - Bullet list of main capabilities
• Screenshots/Demo - Visual examples (if applicable)
• Link to related repos - Main project, other components

Getting Started

• Prerequisites

  • Required software + versions (Node.js 18+, Docker 24+, etc.)
  • System requirements (OS, RAM, etc.)
  • Access requirements (accounts, credentials)

• Installation

  # Step-by-step commands
  git clone ...
  npm install

• Configuration

  • Environment variables (provide .env.example)
  • Config file setup
  • Secrets/credentials setup

• Quick Start

  # One or two commands to get running
  npm run dev

  • Expected output/behavior
  • Where to access (http://localhost:3000)

Development

• Project structure - Brief overview of folders

• Available commands

  • npm run dev - Development server
  • npm run build - Production build
  • npm test - Run tests
  • npm run lint - Linting
  • Other common commands

• Development workflow

  • How to make changes
  • How to test locally
  • Code style guidelines (or link)

• Dependencies

  • Major dependencies explained
  • Why certain choices were made (optional)

Documentation

• Architecture docs - Link to /docs/architecture.md if complex
• API documentation - If applicable
• Additional guides - Links to other docs in /docs/

Contributing

• Link to CONTRIBUTING.md - In .github repo (org-wide)
• How to report bugs - Link to issues
• How to request features - Link to issues
• Development setup - Covered above or link

Additional Info

• License - Clear statement + link to LICENSE file
• Contact/Support - Where to get help, Discord/Slack links
• Acknowledgments - Credits, third-party tools used
• Changelog - Link to CHANGELOG.md or Releases

⚙️ Repository Settings

• Branch protection enabled on main

  • Require PR reviews (at least 1)
  • Require status checks to pass
  • Dismiss stale reviews

• Repository description filled in (shown under repo name)

• Topics/tags added (languages, frameworks, use-case)

• Link to project board (org-level GitHub Projects)

• About section includes:

  • Website (if applicable)
  • Topics
  • License type visible

• Security settings

  • Vulnerability alerts enabled
  • Dependabot enabled (separate ticket)
  • Code scanning enabled (if applicable)

📋 Additional Files

• .env.example - All required environment variables
• .gitignore - Comprehensive for your stack
• LICENSE - Actual license file
• CHANGELOG.md - Or use GitHub Releases
• /docs/ folder - For additional documentation

✨ Nice-to-Have

• Quickstart video/GIF - Visual walkthrough
• Common troubleshooting - FAQ section
• Performance considerations - If applicable
• Deployment guide - How to deploy (or link to deployment repo)
• Roadmap - Future plans (or link to GitHub Projects)
• Comparison table - vs. alternatives (if relevant)

---

🔍 Quality Checks

Before marking as complete:

• All links work
• All commands have been tested
• Instructions are clear to someone unfamiliar with the project
• No internal/private information exposed
• No hardcoded credentials or secrets
• README renders correctly on GitHub

---

Tip: Copy this checklist into each repo's issue and customize based on the specific repository's needs.