Diagnosing TheAlgorithms Contribution Rejections: Structure, Naming, and Conventions

You submitted a pull request to TheAlgorithms that computes the correct result, but the CI check failed and a maintainer asked you to restructure the file. The algorithm works, but TheAlgorithms repos expect self-contained, readable implementations with consistent naming, documentation, and automated hygiene. This guide diagnoses why structurally sound code still gets rejected and offers ordered checks to fix it.

Recognizable condition

The implementation computes the right result locally, but maintainers or CI checks complain about structure, naming, missing explanation, mutable default arguments, broad exceptions, or code that behaves like a script rather than a reusable function. A common example is a Python function defined as def search(terms=[]): the shared list across calls breaks TheAlgorithms' expectation of pure, predictable functions.

Diagnostic overview

Symptom	Likely cause	First check
CI fails on import	File placed outside expected category path	Verify repo root and category folder
Missing doctest	No executable example in docstring	Add a >>> snippet to the docstring
Lint error on line length	Formatter not run	Run the project's configured formatter

Ordered checks

1. Confirm category and filename convention. Before debugging the algorithm, ensure the file belongs to the correct subdirectory (e.g., thealgorithms/python sorting/ directory) and follows the naming pattern snake_case without spaces. Where to run: from the repository root. Permissions: read access to the target folder. Placeholder: path/to/your-algorithm.py. Expected check: the file appears alongside similarly named implementations. Risk: placing the file in the wrong folder forces maintainers to move it, delaying review.

2. Run the repository's configured local checks. Most TheAlgorithms repos ship with a pre-commit config or documented CI commands. Run the same gates CI uses before pushing. Where to run: repository root. Required permissions: execute access. Placeholder command: pre-commit run --all-files or python -m pytest. Expected checks: formatting (black/prettier), lint (flake8/pylint), typing (mypy), and doctests. Risk: fixing only the first failing gate while leaving others unaddressed may cause a subsequent CI failure.

Fixes mapped to findings

• Convention failure: rename or move the file to match the expected path and naming style. Compare your file with an accepted implementation in the same category for reference.

• Missing correctness evidence: add a focused example or doctest that demonstrates the algorithm's input/output without side effects. Keep the snippet short and self-contained.

• Purity violation: remove print statements, file reads, or network calls from the algorithm body. TheAlgorithms prioritizes reusable functions over scripts that produce output.

• Dependency drift: replace project-specific dependencies with standard-library equivalents when possible. For example, use math.gcd instead of a third‑party gcd package if the repo targets portability.

Escalation criteria

Ask maintainers when the failure is ambiguous across language repositories, when a check seems misconfigured rather than caused by the patch, or when the change requires a new category, dependency, or convention exception. Providing the minimal failing output and the diagnostic table above helps maintainers respond faster.

Verification and limitations

Reproduce with a clean checkout and the repository's documented setup, then run the same local quality/test gates used by CI before pushing. Compare your patch against nearby accepted files in the same category for naming, docstring/example style, and absence of side effects. If a gate fails, capture the minimal failing output, fix only that class of issue, rerun the gate, then run the broader suite. Note that TheAlgorithms is a family of repositories; exact gates and folder rules vary by language and over time, so always inspect the specific repo's CONTRIBUTING.md and pre-commit config.