Development

We have tooling for a modern development workflow provided in an environment based around poetry. If there’s another workflow you like better, feel free to use it, but just make sure you’re writing good code, passing tests, and not introducing additional linter errors. In particular, I will enforce conformance with black.

Setup

To set up the development environment:

1. Clone the repo: git clone git@github.com:nihilistkitten/aga.git && cd aga.

2. Install poetry.

3. Install dependencies: poetry install.

4. Activate the development environment: poetry shell.

I encourage you to set up integration between our dev tools and your editor, but it’s not strictly necessary; you can use them as you please, from their CLIs or (I suppose) not at all. Regardless, the environment includes python-lsp-server, which I personally use for this purpose, and can be used via lsp-mode in emacs, atom-languageclient in atom, or the built-in lsp support in neovim and vscode.

Nox

The tool nox runs tooling in virtualized environments. To both run tests and lints, run nox -r (-r prevents nox from reinstalling the environments across multiple runs, which saves significant time.)

Testing

Testing depends on pytest. To run tests, simply run pytest from within the poetry shell. To run tests via nox, run nox -rs test.

Code coverage information can be generated by pytest --cov. This happens by default in nox runs.

There are some network-bound end-to-end tests which are not fun by default. You can run these with pytest -m slow or nox -rs test_slow.

Linting

A number of static analysis tools are available in the development environment:

• mypy, a static type analysis tool.

• pylint, a general-purpose linter.

• flake8, a highly modular linter.

• flake8-black, a code formatting

• checker. flake8-bugbear, which

• makes flake8 stricter. pydocstyle, a

• documentation linter.

These tend to be quite strict, but after a while you’ll get used to them, and they help write much better code.

To run all lints, run nox -rs lint.

Formatting

We use two tools to enforce a uniform code style:

• black, a highly opinionated code formatter.

• isort, an import sorter.

To run both formatters, run nox -rs fmt. This is not run by default runs of nox.

Maintenance

Here I describe how to do common/regular maintenance tasks.

Bump python version

We like to keep the default python version under which tests are run as the most recent stable version (currently 3.10), so that students don’t unknowingly rely on new language features and have to debug versioning differences between their machine and the autograder. Right now, to fix this, we need to:

1. Update the documentation: just grep for 3.10 and replace it with the new version.

2. Update the gradescope build: this is handled in setup.sh; you need to install a different version and change the version we execute the scripts with.

3. Add the new version to be tested in the noxfile.

4. Adjust the shebang of the run_autograder executable.

5. Adjust .readthedocs.yml to build the docs on the newest python.

Add dependencies

Right now, we have a kind of janky setup where we maintain our own setup.py for installing the library on gradescope, in aga/resources/gradescope/setup.py. Whenever we add a dependency, we need to update this file accordingly.