super-gradients/CONTRIBUTING.md

Contribution Guidelines

We appreciate all contributions. If you are planning to contribute back bug-fixes, please do so without any further discussion. If you plan to contribute new features, utility functions or extensions, please first open an issue and discuss the feature with us.

Here are a few more things to know:

• How to Contirbute
• Jupyter Notebooks Contribution
• Code Style Guidelines

How to Contribute

Here is a simple guideline to get you started with your first contribution

1. Use issues to discuss the suggested changes. Create an issue describing changes if necessary and add labels to ease orientation.
2. Fork super-gradients so you can make local changes and test them.
3. Create a new branch for the issue. The branch naming convention is enforced by the CI/CD so please make sure you are using your_username/your_branch_name convention otherwise it will fail.
4. Create relevant tests for the issue, please make sure you are covering unit, integration and e2e tests where required.
5. Make code changes.
6. Ensure all the tests pass and code formatting is up to standards, and follows PEP8.

7. Create a pull request against master branch.

Jupyter Notebooks Contribution

Pulling updates from remote might cause merge conflicts with jupyter notebooks. The tool nbdime might solve this.

• Installing nbdime

pip install ndime

• Run a diff between two notebooks

nbdiff notebook_1.ipynb notebook_2.ipynb

Code Style Guidelines

We are working hard to make sure all the code in this repository is readable, maintainable and testable. We follow the Google docstring guidelines outlined on this styleguide page. For example:

  def python_function(first_argument: int, second_argument: int) -> bool:
      """
      This function will do something with the two arguments.

      Args:
          first_argument (int): the first argument to the function
          second_argument (int): the second argument to the function

      Raises:
          Exception: arguments should be ints not floats

      Returns:
          bool: whether or not the calculation was correct
      """

Documentation

We use GitHub Pages for technical documentation hosting on https://deci-ai.github.io/super-gradients/welcome.html
To generate the docs based on the current work tree, run:
./scripts/generate_docs.sh

And the documentation will automatically update, based on documentation/.
The new documentation HTML will be generated to docs/.
Once docs/ is committed and pushed, GitHub Pages will use it.
The step of documentation update is currently manual.