Contributing a New Algorithm to TheAlgorithms: Minimal Design and CI Checks

Requirements

The algorithm must be correct, include a brief docstring that states time and space complexity, provide a simple usage example, and pass the existing language-specific unit test suite without any modifications.

Smallest Suitable Design

Place a single source file in the language-specific folder, for example java/src/main/java/thealgorithms/search/BinarySearch.java. Expose a public static method that accepts the input data and returns the result, depending only on the language’s standard library.

package thealgorithms.search;

public class BinarySearch {
    /**
     * Performs binary search on a sorted array.
     * @param arr the sorted array to search
     * @param key the value to locate
     * @return index of key, or -1 if not found
     * Time complexity: O(log n), Space complexity: O(1)
     */
    public static int binarySearch(int[] arr, int key) {
        int left = 0;
        int right = arr.length - 1;
        while (left <= right) {
            int mid = left + (right - left) / 2;
            if (arr[mid] == key) {
                return mid;
            }
            if (arr[mid] < key) {
                left = mid + 1;
            } else {
                right = mid - 1;
            }
        }
        return -1;
    }
}

Add a usage comment at the top of the file or in a separate README snippet:

// Example usage:
// int[] data = {2,5,8,12,16};
// int pos = BinarySearch.binarySearch(data, 8); // returns 2

Trust/Data Boundaries

The function treats its arguments as valid per the problem statement. Input validation (e.g., checking for null or unsorted array) is optional and left to the caller. This keeps the algorithm pure, side‑effect free, and easy to reason about in unit tests.

Operational Checks

The repository’s CI runs linters (Checkstyle for Java, pylint for Python, etc.), formatters, and the language-specific test suite. The test suite invokes the algorithm on predefined cases: empty input, large input, duplicate values, and already‑sorted data.

To verify locally, run the appropriate test command from the repository root:

• Java: ./gradlew test
• Python: pytest
• JavaScript: npm test

You need read access to the source tree and write access to the build directory (for compiled classes or cached test reports). The command will fail if any lint rule is violated or if a test does not pass.

Failure Modes

• Logical bugs: produce wrong answers on one or more test cases.
• Performance regressions: cause slower runtime on large inputs, detected by the test suite’s timing checks or by manual benchmarking.
• Breaking changes: e.g., renaming the method or altering its signature cause the existing test harness to fail because it calls the expected method name.

All of these are caught by CI before a merge is allowed.

Conditions That Would Change the Design

If the algorithm truly requires mutating the input (e.g., an in‑place quicksort), the design would shift to accept the array by reference and document the side effect. Adding a non-standard library dependency would necessitate updating the project’s build file and ensuring the dependency passes the repository’s licensing and size checks. Finally, if the language-specific test framework changes (e.g., moving from JUnit 4 to JUnit 5), the test annotation or method signature might need updating, but the core algorithm implementation would remain unchanged.