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.

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.

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 .

Coding style will need to be checked as part of the continuous integration of the project. You can do so by running the flake8 linter in your home directory:

>>> flake8

We also 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. Each assignment has 4 task groups that you will need to pass.

>>> pytest -m task0_0

In addition to running a full task which runs all of the tests, you can run tests in a single file with:

>>> pytest tests/test_operators.py

Or even a particular test with:

>>> 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.

The project also requires that you keep documentation up-to-standard throughout. Lint errors will be thrown if your documentation is in the incorrect format.

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.