CONTRIBUTING.md

Contributing to DSA-Python

Thank you for your interest in contributing! This repository is meant to be a clear, beginner-friendly collection of Data Structures and Algorithms (DSA) in Python. Contributions that improve clarity, coverage, or quality are very welcome.

---

What you can contribute

• New algorithms (e.g., new sorting methods, search techniques, recursion patterns, DP, graph algorithms, etc.).
• New data structures (e.g., stacks, queues, trees, heaps, graphs).
• Improved examples (clearer inputs, better variable names, more comments).
• Documentation (explanations, per-topic READMEs, complexity notes).
• Refactoring for clarity (without changing the underlying algorithmic logic).

Please keep contributions educational and beginner-friendly.

---

Repository structure (high-level)

• 0 Python/ – Python basics and simple DSA practice.
• 1 Basic_Maths/ – Number theory and basic math problems.
• 2 Sorting/ – Sorting algorithms.
• 3 Arrays/ – Array ADT and array-based algorithms.
• 4 Binary Search/ – Binary search implementations.
• 5 Hashing/ – Introductory hashing.
• 6 Recursion/ – Recursion examples and patterns.
• 7 Strings/ – String algorithms and problems.
• 8 Linked List/ – Linked list implementations.

When adding new code, try to place it in the most appropriate existing folder. If you feel a new topic folder is needed, briefly explain your reasoning in the pull request.

---

Code style and design guidelines

To keep the repository consistent and easy to learn from:

• One concept per file

  • Prefer binary_search_recursive.py + binary_search_iterative.py over one large file with many unrelated algorithms.
  • If a file must contain multiple functions, keep them closely related and clearly separated with comments.

• Clear, descriptive naming

  • Use lowercase with underscores for file and function names (e.g., reverse_string.py, linear_search.py).
  • Variable names should be meaningful (e.g., arr, left, right, key, head, node, not a, b, c).

• Comments and explanation

  • At the top of each file, briefly state:
    • What the algorithm/data structure does.
    • Any assumptions (sorted input, constraints, etc.).
  • Add inline comments for tricky parts of the logic.
  • Include time and space complexity (Big-O) in a short comment near the function or at the top of the file.

  Example:

  # Binary Search (Iterative)
  # Time Complexity: O(log n)
  # Space Complexity: O(1)

• Input/output style

  • Prefer self-contained examples:
    • Define sample input inside the file.
    • Print the result clearly.
  • If you need user input, validate and document the expected format in comments.

• Dependencies

  • Prefer the Python standard library.
  • External libraries should only be used when they make the concept clearer (e.g., numpy in one or two educational examples).
  • Do not add heavy dependencies or frameworks.

• Formatting

  • Stick to standard Python conventions (PEP 8 as a soft guideline).
  • Use 4 spaces for indentation.
  • Keep lines reasonably short and readable.

---

Running scripts and testing

Most scripts are simple, standalone Python files.

Prerequisites

• Python 3.x installed.

Running a script

From the repository root:

cd "3 Arrays/Python"
python3 "00 arrayADT.py"

Adjust the path and filename for the script you want to run. For example:

cd "2 Sorting/Python"
python3 bubblesort.py

If a script requires an extra library (for example, numpy in some array examples), install it with:

pip install numpy

If you add a script that needs external libraries, clearly mention them in comments at the top of the file and in your pull request description.

---

How to add a new algorithm or example

1. Choose the right folder

   • Example: A new recursion example → 6 Recursion/Python (if that substructure exists) or the closest matching folder.
   • If unsure, pick the closest topic and explain your choice in the PR.

2. Create a new file

   • Use a descriptive name, e.g., merge_sort.py, two_sum.py, reverse_linked_list.py.

3. Document the file

   • At the top, include:
     • Short description.
     • Time and space complexity.
     • Any constraints or assumptions.

4. Add example usage

   • At the bottom of the file, show how the function is used with a small example.
   • Print the output clearly so learners can see what happens.

5. Test your code

   • Run the script locally:

     python3 your_script.py

   • Make sure it runs without errors and behaves as expected.

---

Submitting a pull request (PR)

1. Fork the repository on GitHub.
2. Create a new branch in your fork:

   git checkout -b feature/new-algorithm-name

3. Make your changes (add files, update documentation, etc.).
4. Run your scripts to ensure they work.
5. Commit with a clear message:

   git commit -m "Add merge sort example in Python"

6. Push your branch:

   git push origin feature/new-algorithm-name

7. Open a Pull Request:
   • Describe:
     • What you added or changed.
     • Where the new file lives.
     • Any dependencies or assumptions.
   • If the change relates to an existing issue, mention it.

---

Review process

• The maintainer (or other contributors) will review your PR.
• You may be asked to:
  • Adjust file names or folder placement.
  • Improve comments or complexity explanations.
  • Tidy up formatting.
• Once everything looks good, your PR will be merged.

Thank you again for helping make this DSA-Python repository more useful for learners and interview prep!