CONTRIBUTING.md

Contributing

Contributions are welcome, and they are greatly appreciated. Every little bit helps, and credit will always be given.

Developing

Ready to contribute? Here's how to set up your environment for local development.

1. Clone the fork locally and change directory:

   # With SSH:
   git clone [email protected]:itsdawei/dpvis.git
   
   # Without SSH:
   git clone https://github.com/itsdawei/dpvis.git
   
   cd dpvis

2. There are a few options to managing virtual environment:

   • (Recommended) Install Conda and run:

     conda create -n dpvis python=3.11
     conda activate dpvis
     pip install -e .[dev]

   • Alternatively, install Poetry and run:

     poetry install

   • Although highly recommended, a virtual environment is not necessary as long as you have Python 3.9+ and a Python package manager such as pip. In this case, you can install the library directly with:

     pip install -e .[dev]

3. (Optional) Run knapsack demo to verify installation:

   poetry shell
   python demos/knapsack.py
   exit

4. Create a branch for local development:

   git checkout -b name-of-bugfix-or-feature

   Now make the appropriate changes locally.

   • Please follow the Google Style Guide (particularly when writing docstrings).

   • Make sure to auto-format the code using YAPF. We highly recommend installing an editor plugin that auto-formats on save, but YAPF also runs on the command line:

     yapf -i FILES

5. After making changes, check that the changes pass the tests:

   pytest tests/
   make test # ^ same as above

   Finally, to lint the code:

   pylint dp tests
   make lint # ^ same as above

   To get pytest and pylint, pip install them into the environment. However, they should already install with pip install -e .[dev].

6. Add your change to the changelog for the current version in HISTORY.md.

7. Commit the changes and push the branch to GitHub:

   git add .
   git commit -m "Detailed description of changes."
   git push origin name-of-bugfix-or-feature

8. Submit a pull request through the GitHub website.

Pull Request Guidelines

Before submitting a pull request, check that it meets these guidelines:

1. Style: Code should follow the Google Style Guide and be auto-formatted with YAPF.
2. The pull request should include tests.
3. If the pull request adds functionality, corresponding docstrings and other documentation should be updated.
4. The pull request should work for Python 3.7 and higher. GitHub Actions will display test results at the bottom of the pull request page. Check there for test results.

Instructions

Running a Subset of Tests

To run a subset of tests, use pytest with the directory name, such as:

pytest tests/core/test1

Documentation

The documentation is compiled with mkdocs-material and mkdocstrings

To serve the documentation locally, run

poetry install --with docs
poetry run make servedocs

Referencing Papers

When referencing papers, refer to them as Lastname YEAR, e.g. Smith 2004. Also, prefer to link to the paper's website, rather than just the PDF. This is particularly relevant when linking to arXiv papers.