README-dev.md

BackPACK developer manual

General standards

• Python version: support 3.8+, use 3.8 for development
• git branching model
• Docstring style: Google
• Test runner: pytest
• Formatting: black (black config)
• Linting: flake8 (flake8 config)

---

The development tools are managed using make as an interface (makefile). For an overview, call

make help 

Suggested workflow with Anaconda

1. Clone the repository. Check out the development branch

git clone https://github.com/f-dangel/backpack.git ~/backpack
cd ~/backpack
git checkout development

2. Create conda environment backpack with the environment file. It comes with all dependencies installed, and BackPACK installed with the --editable option. Activate it.

make conda-env
conda activate backpack

3. Install the development dependencies

make install-dev

4. You're set up! Here are some useful commands for developing

• Run the tests

  make test

• Lint code

  make flake8

• Check format (code, imports, and docstrings)

  make format-check

Pull requests

Code that is affected (has a git diff) by a pull request must satisfy the following docstring requirements:

1. A one-line summary what the function/class does
2. Argument description (Args section)
   • Argument name, type, and description
   • Optional arguments must be marked as such, the default value must be documented in the description
3. Output description (Returns section)
   • Type and description

Documentation

Build

• Use make build-docs
• To use the RTD theme, uncomment the line html_theme = "sphinx_rtd_theme" in docs/rtd/conf.py (this line needs to be uncommented for automatic deployment to RTD)

View

• Go to docs_src/rtd_output/html, open index.html

Edit

• Content in docs_src/rtd/*.rst
• Docstrings in code
• Examples in examples/rtd_examples (compiled automatically)

Details

• Running quick/extensive tests: (testing readme)
• Continuous Integration (CI)/Quality Assurance (QA)
  • Travis (Travis config)
    • Run tests: pytest
    • Report test coverage: coveralls
    • Run examples
  • Github workflows (config)
    • Check code formatting: black (black config)
    • Lint code: flake8 (flake8 config)
    • Check docstring style: pydocstyle (pydocstyle config)
    • Check docstring description matches definition: darglint (darglint config)

BackPACK is not endorsed by or affiliated with Facebook, Inc. PyTorch, the PyTorch logo and any related marks are trademarks of Facebook, Inc.