Contributing

Each MiniTorch assignment is structured to mimic the experience of contributing to a real open-source project. Thus we have specific contributor requirements. This doc lays out our expectation of your code. For each assignment, there is a script run_test.py available for you to check each of the necessary properties before submitting:

>>> python run_tests.py

You can also run an individual test group:

>>> python run_tests.py 2

Style

It is required to keep your code organized and clean to make it easier to debug, optimize, and document. To help with this process, we utilize required formatting on all assignments. Coding style is checked in run_tests.py 0 automatically.

Fixing style bugs can be an annoying process. However, there is a nice trick to fix most formatting issues automatically. We use black to automatically reformat all of your code to fit most of the requirements (see https://github.com/psf/black for more details):

>>> black minitorch/ tests/ project/

We recommend setting up your editor or IDE to highlight other style issues.

Testing

Each assignment has a series of tests that require your code to pass. These tests are in the tests/ directory and are in the pytest format (https://docs.pytest.org/en/stable/). Any function in that directory with the word test in its name is run as part of the test suite.

In addition to run_tests.py which runs all of the tests, you can run tests in a single file with:

>>> python -m pytest tests/test_operators.py

Or even a particular test with:

>>> python -m pytest tests/test_operators.py -k test_sum

Pytest will hide all print statements unless a test fails.

Documentation

Throughout the codebase, we require to document all functions in a standardized style. Documentation is critical for our Python codebase, and we use it to convey requirements on many functions. Functions should have docstrings in the following form (known as Google docstyle):

def index(ls, i):
    """
    List indexing.

    Args:
        ls (list): A list of any type.
        i (int): An index into the list

    Returns:
        Value at ls[i].
    """
    ...

A full description of this docstyle is listed here https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html.

Continuous Integration (CI)

In addition to local testing, the project is set up such that on each code push, tests are automatically run and checked on the server. You are able to see how well you are doing on the assignment by committing your code, pushing to the server, and then logging in to GitHub. This process takes several minutes, but it is an easy way to keep track of your progress as you go.

Specifically, you can run:

>>> git commit -am "First commit";
>>> git push origin master

Then go to your GitHub and click on "Pull requests". Clicking on the request itself gives a link to show the current progress of your work.