Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
439 lines (362 loc) · 18.1 KB

CONTRIBUTING.md

File metadata and controls

439 lines (362 loc) · 18.1 KB

Contributing Guide

Welcome to the Algorithms repository! We are building a curated, multi-language collection of 248 algorithms with 2,402 implementations across 11 languages, organized by category. Every contribution goes through templates, automated validation, and maintainer review to ensure consistent quality across the entire project.

For more on our project goals, see the README.

The maintainer of the project is Thuvarakan.

Table of Contents

Repository Structure

This repository follows a category-first organization. Every algorithm lives under its category, and each algorithm directory contains documentation, test cases, and implementations in one or more languages.

algorithms/
└── sorting/
    └── bubble-sort/
        ├── README.md
        ├── metadata.yaml
        ├── tests/
        │   └── cases.yaml
        ├── python/
        │   └── bubble_sort.py
        ├── java/
        │   └── BubbleSort.java
        └── ...

Each algorithm directory contains:

File/Directory Purpose
README.md Educational explanation of the algorithm (overview, steps, complexity, use cases)
metadata.yaml Structured metadata (name, category, complexity, tags, related algorithms)
tests/cases.yaml Test cases with inputs and expected outputs (minimum 5, including edge cases)
{language}/ One subdirectory per language implementation

How to Contribute

Adding a New Algorithm

  1. Check if the algorithm already exists. Browse the algorithms/ directory or search the README table to make sure the algorithm has not already been added.

  2. Fork the repository and create a branch.

    git checkout -b add/{category}/{algorithm-slug}

  3. Scaffold the algorithm directory. Use the scaffold script to generate all boilerplate:

    npm run scaffold -- --name "Algorithm Name" --slug algorithm-slug --category sorting --difficulty intermediate

    This creates the full directory structure with template files for metadata.yaml, README.md, tests/cases.yaml, and empty directories for all 11 languages.

  4. Fill in metadata.yaml. Copy the template from templates/metadata-template.yaml and fill in all fields:

    • name -- Human-readable algorithm name
    • slug -- Kebab-case identifier (must match directory name)
    • category -- One of the 14 supported categories
    • subcategory -- More specific grouping (optional)
    • difficulty -- beginner, intermediate, or advanced
    • tags -- Searchable keywords
    • complexity -- Time (best, average, worst) and space in Big-O notation
    • stable -- Whether the algorithm is stable (true, false, or null if not applicable)
    • in_place -- Whether the algorithm operates in place (true, false, or null)
    • related -- Slugs of related algorithms
    • implementations -- List of languages with implementations
    • visualization -- true or false

  5. Add README.md. Copy the template from templates/algorithm-readme-template.md. The README must include all of these sections:

    • Overview
    • How It Works (with a worked example)
    • Pseudocode
    • Complexity Analysis (table with best/average/worst time and space)
    • When to Use / When NOT to Use
    • Comparison with Similar Algorithms
    • References

  6. Add tests/cases.yaml. Copy the template from templates/test-cases-template.yaml. Requirements:

    • Minimum 5 test cases
    • Must include edge cases (empty input, single element, etc.)
    • Must define the function_signature (name, input types, output type)
    • All implementations must match this signature

  7. Add at least one language implementation. Create a subdirectory for the language (e.g., python/) and add your implementation file following the file naming conventions. The function must match the signature defined in tests/cases.yaml.

  8. Run validation.

    node scripts/validate-structure.mjs

    Fix any errors before submitting.

  9. Submit a pull request. Follow the PR requirements below.

Adding a Language Implementation to an Existing Algorithm

  1. Find the algorithm directory. Navigate to algorithms/{category}/{algorithm-slug}/.

  2. Read the existing tests/cases.yaml. Understand the function signature and all test cases your implementation must pass.

  3. Create the language subdirectory.

    mkdir algorithms/{category}/{algorithm-slug}/{language}

  4. Implement the algorithm.

  5. Update metadata.yaml. Add your language to the implementations list.

  6. Submit a pull request.

Code Standards

File Naming Conventions

Each language has its own convention. Use the table below:

Language Convention Example
Python snake_case.py bubble_sort.py
Java PascalCase.java BubbleSort.java
C++ snake_case.cpp bubble_sort.cpp
C snake_case.c bubble_sort.c
Go snake_case.go bubble_sort.go
TypeScript camelCase.ts bubbleSort.ts
Kotlin PascalCase.kt BubbleSort.kt
Rust snake_case.rs bubble_sort.rs
Swift PascalCase.swift BubbleSort.swift
Scala PascalCase.scala BubbleSort.scala
C# PascalCase.cs BubbleSort.cs

Implementation Guidelines

  • Match the function signature defined in tests/cases.yaml exactly.
  • Write idiomatic code for the language (e.g., use Pythonic patterns in Python, proper error handling in Rust, etc.).
  • Document your code with clear comments explaining the logic and key steps.
  • Include standard optimizations where applicable (e.g., early termination in bubble sort when no swaps occur in a pass).
  • Keep it clean -- no dead code, no debugging statements, consistent formatting.

PR Requirements

All pull requests must meet the following criteria before they will be merged:

  1. Structure validation passes. Run node scripts/validate-structure.mjs and ensure zero errors.
  2. All test cases pass for every submitted implementation.
  3. README.md follows the template with all required sections filled in.
  4. metadata.yaml is complete and accurate -- all fields populated, complexity values correct.
  5. Maintainer review required. Every PR is reviewed by a maintainer before merging. Expect feedback on code quality, documentation clarity, and test coverage.

Quality Bar

This is a curated repository. We hold contributions to a high standard:

  • Implementations must be idiomatic for their language. A Java solution should look like good Java, not transliterated Python.
  • Test cases must cover edge cases -- empty inputs, single elements, already-sorted data, negative numbers, large inputs, duplicates, and any other boundary conditions relevant to the algorithm.
  • Documentation must be educational and accurate. The README should teach someone how the algorithm works, not just describe it. Complexity analysis must be correct and explained.

Supported Languages

This project accepts implementations in the following 11 languages:

  1. Java
  2. Python
  3. C
  4. C++
  5. Go
  6. TypeScript
  7. Kotlin
  8. Rust
  9. Swift
  10. Scala
  11. C#

Categories

All algorithms are organized into one of the following 14 categories:

Category Description
sorting Algorithms that arrange elements in a specific order
searching Algorithms for finding elements or values within data structures
graph Algorithms operating on graph structures (traversal, shortest path, MST, etc.)
dynamic-programming Optimization problems solved by breaking them into overlapping subproblems
trees Algorithms for tree data structures (traversal, balancing, construction)
strings String matching, manipulation, and parsing algorithms
math Number theory, combinatorics, arithmetic, and other mathematical algorithms
greedy Algorithms that make locally optimal choices at each step
backtracking Algorithms that explore all possibilities by building candidates and abandoning those that fail
divide-and-conquer Algorithms that break problems into smaller subproblems, solve them independently, and combine results
bit-manipulation Algorithms that operate directly on binary representations of numbers
geometry Computational geometry algorithms (convex hull, line intersection, etc.)
cryptography Encryption, hashing, and other security-related algorithms
data-structures Implementations and operations on fundamental data structures

Scaffold Script

The scaffold script generates all boilerplate for a new algorithm:

npm run scaffold -- --name "Algorithm Name" --slug algorithm-name --category sorting --difficulty intermediate

This creates:

  • algorithms/{category}/{slug}/metadata.yaml -- Pre-filled with your values
  • algorithms/{category}/{slug}/README.md -- Template with all required sections
  • algorithms/{category}/{slug}/tests/cases.yaml -- Template with 5 test case slots
  • Empty directories for all 11 languages

Run npm run scaffold -- --help for full usage details.

PR Validation Bot

When you open a pull request, a GitHub Action automatically validates any modified algorithm directories. It checks:

  • metadata.yaml exists with all required fields (name, slug, category, difficulty, complexity)
  • README.md exists
  • tests/cases.yaml exists with at least 1 test case
  • Category is one of the 14 valid categories
  • Difficulty is beginner, intermediate, or advanced

The bot posts a comment on your PR summarizing validation results. Fix any reported errors before requesting review.

Requesting Algorithms or Implementations

If you want to request a new algorithm or a language implementation without contributing code yourself, use the issue templates:

Getting Help

If you have questions or need guidance:

  • Open an issue on the Issues page
  • Check existing issues and pull requests for context
  • Review the templates in the templates/ directory for examples of what is expected

Contributors

Thanks to everyone who has contributed to this repository.