Skip to content

Latest commit

 

History

History
235 lines (184 loc) · 7.62 KB

CONTRIBUTING.md

File metadata and controls

235 lines (184 loc) · 7.62 KB

Contributing

Contributions are welcome and are greatly appreciated! Every little bit helps. Contributions include reporting/fixing bugs, proposing/implementing features (see our Issue Tracker), writing documentation in the codebase, and submitting feedback.

Developing qdglue

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

  1. Fork the qdglue repo on GitHub.

  2. Clone the fork locally:

    # With SSH:
git clone [email protected]:USERNAME/qdglue.git

# Without SSH:
git clone https://github.com/USERNAME/qdglue.git

  3. Create a branch for local development:

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

  4. Install the local copy and dev requirements into a virtual environment. For instance, with Conda, the following creates an environment at ./env.

    cd qdglue
conda create --prefix ./env python=3.7 # 3.7 is the minimum version qdglue supports.
conda activate ./env
pip install -e .[dev]

  5. We roughly follow the Google Style Guide in our codebase by using black, isort, and pylint to enforce code format and style. To automatically check for formatting and style every time you commit, we use pre-commit. Pre-commit should have already been installed with .[dev] above. To set it up, run:

    pre-commit install

  6. Now make the appropriate changes locally. If relevant, make sure to write tests for your code in the tests/ folder.

  7. Auto-format and lint your code using black, isort, and pylint. We highly recommend installing editor plugins that perform these operations on save, but you can also run on the command line:

    black FILES
isort FILES
pylint FILES

    Note that these checks are also run by pre-commit whenever you commit your code.

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

    pytest tests/
make test # ^ same as above

    And to run the benchmarks:

    pytest -c pytest_benchmark.ini
make benchmark # ^ same as above

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

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

  11. Submit a pull request through the GitHub web interface.

Instructions

Running a Subset of Tests

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

pytest tests/core/archives

Documentation

Documentation is primarily written in Markdown, as we use mkdocs.

To preview documentation, use:

make servedocs

This will show a localhost URL that you can open in your browser; any changes will automatically reload the page.

Adding a Tutorial

(Forthcoming)

Tutorials are created in Jupyter notebooks that are stored under tutorials/ in the repo. To create a tutorial:

  1. Write the notebook and save it under tutorials/.

  2. Use cell magic (e.g. %pip install qdglue) to install qdglue and other dependencies.

    • Installation cells tend to produce a lot of output. Make sure to clear this output in Jupyter lab so that it does not clutter the documentation.

  3. Before the main loop of the QD algorithm, include a line like total_itrs = 500 (any other integer will work). This line will be replaced during testing (see tests/tutorials.sh) in order to test that the notebook runs end-to-end. By default, the tests run the notebook with total_itrs = 5. If this tutorial needs more (or less), modify the switch-case statement in tests/tutorials.sh.

  4. Make sure that the only level 1 heading (e.g. # Awesome Tutorial) is the title at the top of the notebook. Subsequent titles should be level 2 (e.g. ## Level 2 Heading) or higher.

  5. If linking to the qdglue documentation, make sure to link to pages in the latest version on ReadTheDocs, i.e. your links should start with https://docs.pyribs.org/en/latest/

    TODO: update link above

  6. Add an entry into the toctree in docs/tutorials.md and add it to one of the lists of tutorials.

  7. Check that the tutorial shows up on the Tutorials page when serving the docs.

Adding an Example

(Forthcoming)

Examples are created in Python scripts stored under examples/ in the repo, and their source is shown in the docs. To create an example:

  1. Write the Python script and save it under examples/.

  2. Add any dependencies at the top of the script with a pip install command (see existing examples for a sample of how to do this).

    TODO(btjanaka): We currently install requirements in examples/requirements.txt; may want to change this in the future.

  3. Add a shell command to tests/examples.sh that calls the script with parameters that will make it run as quickly as possible. This helps us ensure that the script has basic correctness. Also call the install_deps function on the script file before running the script.

  4. Add a Markdown file in the docs/examples directory with the same name as the Python file -- if the example is examples/foobar.py, the Markdown file will be docs/examples/foobar.md.

  5. Add a title to the Markdown file, such as:

    # My Awesome Example

  6. In the markdown file, include the following so that the source code of the example is displayed.

    ```{eval-rst}
.. literalinclude:: ../../examples/EXAMPLE.py
    :language: python
    :linenos:
```

  7. Add any other relevant info to the Markdown file.

  8. Add an entry into the toctree and list of examples in docs/examples.md.

  9. Check that the example shows up on the Examples page when serving the docs.

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.

Deploying

(Forthcoming)

  1. Create a PR into master after doing the following:
    1. Switch tutorial links from latest to stable with: 
      make tutorial_links
      See pyribs #300 for why we do this.
    2. Update the version with bump2version by running the following for minor versions: 
      bump2version minor
      or the following for patch versions: 
      bump2version patch
    3. Add all necessary info on the version to HISTORY.md.
  2. (Optional) Once the PR has passed CI/CD and been squashed-and-merged into master, check out the squash commit and locally run make release-test. This uploads the code to TestPyPI to check that the deployment works. If this fails, make fixes as appropriate.
  3. Once the PR in step 1 and any changes in step 2 have passed CI/CD and been squashed-and-merged into master, locally tag the master branch with a tag like v0.2.1, e.g. 
    git tag v0.2.1 HEAD
  4. Now push the tag with 
    git push --tags
  5. Check that the version was deployed to PyPI. If it failed, delete the tag, make appropriate fixes, and repeat steps 2 and 3.
  6. Write up the release on GitHub, and attach it to the tag.
  7. Submit another PR which reverts the changes to the tutorial links. Specifically, while on master, make sure your workspace is clean, then revert the changes with: 
    git checkout HEAD~ tutorials/
    And commit the result.

Our deployment process may change in the future as qdglue becomes more complex.