Contributing

Contributing

Want to contribute a project? Here's how to get started.

For the full, detailed contributing guide, see CONTRIBUTING.md in the repository.

Quick Overview

1. Fork the repository
2. Create your project in PROJECTS/{difficulty}/{project-name}/
3. Include a learn/ folder with educational documentation
4. Submit a pull request

Project Structure

Projects live in difficulty-based directories:

PROJECTS/
├── beginner/           # Basic tools, single-file scripts
├── intermediate/       # Multi-component systems, API integrations
└── advanced/           # Full-stack apps, distributed systems

Naming convention: lowercase, hyphenated (e.g., api-security-scanner, dns-lookup)

Required: learn/ Folder

Every project must include a learn/ directory with five educational files:

File	Content
00-OVERVIEW.md	What it does, prerequisites, quick start
01-CONCEPTS.md	Security theory, real breaches, CVE references
02-ARCHITECTURE.md	System design with ASCII diagrams
03-IMPLEMENTATION.md	Code walkthrough with file:line references
04-CHALLENGES.md	Extension ideas from easy to expert

Copy the template from .github/learn-folder-template/ to get started.

Package Managers

• Python: Use uv (not pip)
• Node.js: Use pnpm or Bun (not npm)

Code Quality

All Python code must pass:

• ruff check . (linting)
• mypy . (type checking)
• pylint src/ (additional linting)

Format with the repo's YAPF configuration (see TEMPLATES/.style.yapf).

Documentation Standards

• Reference actual code with filename:line format
• Include real-world examples (breaches, CVEs, incidents)
• Use ASCII diagrams for architecture
• Write in a clear, human voice (no marketing speak)
• Ground concepts in real-world security scenarios

Full-Stack Template

Building a full-stack app? Use the included fullstack-template with FastAPI, React, Docker, and more.

Questions?

Open an issue to discuss project ideas before starting.