Ctrl+K

Contributor’s Guide

Contributor’s Guide#

Welcome to the Contributor’s Guide for candle!

Welcome to the team! If you are reading this document, we hope that you are already or soon-to-be a candle library contributor, please keep reading!

1. Overview#

The CANDLE library enables users to run their own deep learning code on a set of supported high-performance computers. With the current version of CANDLE, users will be able to run a hyperparameter optimization task (mlrMBO workflow) or a parallel execution task (upf workflow).

We invite other community members to become part of this collaboration at any level of contribution.

1.1. Many Ways to Contribute#

There are many different ways to contribute to candle_lib. Anyone can, for example:

  • Adding new functionality

    • python function <fname> in candle/ folder

    • Add the this file in docs/api_<fname>/index.rst

    • Specify the API functions for inclusion in ReadTheDocs (RTD)

  • Extending functionality of existing modules (say candle/file_utils.py)

    • Add the API functions in the corresponding index.rst file (eg. docs/api_file_utils/index.py)

  • Write or revise documentation (including this document)

    • Documentation can be built locally by run running ‘make html’ from the docs folder

    • Python dependencies can for this documentation are listed in docs/NOTES.txt

    • After building documentation can be visualized locally using any browser from file docs/_build/html/index.html

  • Develop example notebooks that demonstrate how a particular function is used

  • Answer a support question

  • Request a feature or report a bug

All of these activities are signicant contributions to the on-going development and maintenance of candle lib.

1.2 Getting Started with GitHub and Git#

Contributing to candle_lib requires using GitHub, and contributing to a GitHub repository follows almost the same process by any open source Python project maintained on GitHub. However, it can still seem complex and somewhat varied from one project to another. As such, we will refer the reader to comprehensive resources for basic learning and detailed information about GitHub (such as the Getting Started with Github guide).

  • Assertions are used for testing various cases such as array comparison.

  • Please see previously implemented test cases for reference of the recommended testing approach

Attention

Our test suite that includes all the unit tests is executed automatically for PRs with the help of GitHub Actions workflows to ensure new code passes tests. Hence, please check `3.7.4.2. GitHub Actions checks`_ to make sure your PR tests are all passing before asking others to review your work.

1.3. GitHub Actions checks#

candle_lib employs a number of GitHub Actions workflows (please refer to the GitHub Actions guide for detailed information) to make sure our PRs, branches, etc. pass certain test scenarios such as the pre-commit hooks, code test suite, and documentation generation. The pre-commit hooks workflow ensures the code being proposed to be merged is complying with code standards.

Note

All PRs must be made to the develop branch. We require PRs to pass all of these checks before getting merged in order to always ensure our develop branch stability.

These checks can be extremely helpful for contributors to be sure about they are changing things in correct directions and their PRs are ready to be reviewed and merged.

Contents