How to Contribute a New Algorithm to The Algorithms Repository Without Getting Rejected

The problem: most first PRs to The Algorithms fail for predictable reasons

The Algorithms is a multi-language open-source collection of algorithm implementations (Python, Java, C++, JavaScript, Rust, Go, and more). Because it is popular with first-time contributors, maintainers reject a large share of pull requests — usually for duplicates, missing tests, wrong complexity annotations, or lint failures. The useful takeaway: nearly every rejection cause is checkable locally before you push. This guide walks through the full contribution path, from picking an algorithm that isn't already there to verifying your merged work on the documentation site.

Conventions described here reflect the repository's long-standing structure. Because CI configuration and scripts change over time, treat specific command names as things to confirm against the current CONTRIBUTING.md and workflow files in the repo before relying on them.

Prerequisites

• A GitHub account and a fork of TheAlgorithms/<language> (the project is split into per-language repositories, e.g., TheAlgorithms/Python).
• The language toolchain installed locally: Python 3 with pytest, a JDK with Maven for Java, a Rust toolchain with cargo, etc.
• Git configured with an upstream remote pointing at the original repository so you can rebase later.
• A local clone of your fork.

Step 1: Confirm the algorithm isn't already there

Duplicate submissions are the most common rejection reason. Search case-insensitively across the whole repository, because the same algorithm may exist under a variant name ("quicksort" vs. "quick_sort" vs. "quick sort"):

# Run inside your local clone; no special permissions needed
grep -ri "quick.*sort" --include="*.py" .

Also search the merged and open PR lists on GitHub for the algorithm name — someone else may have submitted it recently. If the repository provides a duplicate-detection script (check for something like scripts/check_duplicates.py in the current tree), run it as well.

Step 2: Create a focused branch and place the file correctly

Create one branch per algorithm, per language. Large PRs bundling unrelated algorithms are routinely sent back to be split.

git checkout -b add-timsort-python

Each repository uses standardized category folders such as sorts/, searches/, and dynamic_programming/. Put your implementation in the matching category with a snake_case (Python) or language-appropriate filename, e.g., sorts/tim_sort.py.

Step 3: Write the implementation with accurate complexity annotations

Every implementation needs a docstring or header comment explaining what the algorithm does plus its time and space complexity. Incorrect Big-O claims are a frequent rejection reason, so verify your annotation against a reference rather than guessing. A minimal Python example:

def counting_sort(arr: list[int]) -> list[int]:
    """Sort a list of non-negative integers using counting sort.

    Time complexity:  O(n + k), where k = max(arr)
    Space complexity: O(k)

    >>> counting_sort([4, 2, 2, 8, 3])
    [2, 2, 3, 4, 8]
    >>> counting_sort([])
    []
    """
    if not arr:
        return []
    k = max(arr)
    count = [0] * (k + 1)
    for x in arr:
        count[x] += 1
    out = []
    for value, freq in enumerate(count):
        out.extend([value] * freq)
    return out

Two constraints to respect: use only the standard library unless the algorithm genuinely requires an approved well-known library (e.g., NumPy for numerical code), and make sure the code passes the repo's configured linter (flake8/ruff for Python, checkstyle for Java, clang-format for C++, eslint for JavaScript).

Step 4: Add tests using the project's naming convention

A corresponding test file is mandatory. Follow the existing convention — test_<algorithm>.py for pytest, <Algorithm>Test.java for JUnit, and so on. Cover typical input, empty input, single-element input, already-sorted input, and any domain restrictions (e.g., counting sort's non-negative integer requirement):

from sorts.counting_sort import counting_sort

def test_typical():
    assert counting_sort([4, 2, 2, 8, 3]) == [2, 2, 3, 4, 8]

def test_empty_and_single():
    assert counting_sort([]) == []
    assert counting_sort([7]) == [7]

def test_already_sorted():
    assert counting_sort([1, 2, 3]) == [1, 2, 3]

Step 5: Run the local checks CI will run

The GitHub Actions pipelines run language-specific linters, the unit test suite, and a documentation build; all must pass before merge. Reproduce them locally from the repository root (confirm exact targets in the current CONTRIBUTING.md or Makefile):

# Python repo examples — run from the repo root, no elevated permissions
ruff check sorts/counting_sort.py
pytest sorts/counting_sort.py tests/ -k counting_sort --doctest-modules

For other languages the equivalents are typically mvn test (Java), cargo test (Rust), or npm run lint && npm test (JavaScript). Expected check: zero lint findings and all tests passing. Do not push until both are clean.

Step 6: Open the PR and respond to review

Push the branch to your fork and open a PR with a descriptive title that names the algorithm and language, e.g., "Add counting sort in Python". At least one maintainer approval is required. Reviewers check correctness, complexity annotations, test coverage, style compliance, and duplication.

Recovery: when CI fails or the branch goes stale

If a workflow fails, open the Actions tab on your PR, read the failing job's log, fix the issue locally, re-run the local check, then push to the same branch — the push re-triggers CI automatically. No new PR is needed.

If your branch conflicts with main while waiting for review, rebase rather than merge:

git fetch upstream
git rebase upstream/main
# resolve conflicts, then:
git push --force-with-origin

Force-pushing rewrites your branch history; it is safe here only because the branch is yours alone. Maintainers may also ask you to squash commits before merge.

Verifying the merged result

After merge, the algorithm should appear on the auto-generated documentation site (thealgorithms.github.io) within roughly a day via scheduled deployment. Navigate to the relevant language section and confirm your file is listed with the correct complexity information. If it is missing after 48 hours, check whether the docs workflow ran successfully on the main branch before opening an issue.

Limitations

Exact linter versions, script names, and required workflow checks change as the project evolves; the authoritative source is always the current CONTRIBUTING.md and the .github/workflows/ directory in the repository you are targeting. This guide describes the general decision path, not a guaranteed checklist for any specific date.