Skip to content

Latest commit

 

History

History
102 lines (75 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

102 lines (75 loc) · 4.15 KB
Raw

Contributing to ΦFlow

All contributions are welcome! You can mail the developers to get in touch.

Types of contributions we're looking for

We're open to all kind of contributions that improve or extend the ΦFlow library. We especially welcome

  • New equations / solvers
  • Code optimizations or native (CUDA) implementations.
  • Integrations with other computing libraries.
  • Bug fixes

ΦFlow is a framework, not an application collection. While we list applications in the demos directory, these should be short and easy to understand.

How to Contribute

We recommend you to contact the developers before starting your contribution. There may already be similar internal work or planned changes that would affect how to code the contribution.

To contribute code, fork ΦFlow on GitHub, make your changes, and submit a pull request. Make sure that your contribution passes all tests.

For commits, we use the following tags in the header:

  • [doc] for documentation updates
  • [ci] for CI configuration changes
  • [build] for changes to the installation
  • [tests] for adding or changing unit tests
  • [demos] for adding or changing demo scripts
  • [Φ] for general changes like version numbers or default imports

If the commit modifies the main codebase (phi/), use one of the following tags:

  • [vis] for general changes in phi.vis as well as changes to any GUI, e.g. dash, widgets, console.
  • [geom] for changes to phi.geom
  • [field] for changes to phi.field except Scene
  • [io] for changes to Scenes, data layout
  • [physics] for changes to phi.physics
  • [learning] for non-backend changes to phi.tf, phi.torch

Example commit header: [doc] Improve markdown layout

Commits may be tagged with multiple tags, but this should be used sparingly.

Bugfix commits are tagged with the module to which the fixes are applied.

Style Guide

Style guidelines make the code more uniform and easier to read. Generally we stick to the Python style guidelines as outlined in PEP 8, with some minor modifications outlined below.

Have a look at the Zen of Python for the philosophy behind the rules. We would like to add the rule Concise is better than repetitive.

We use PyLint for static code analysis with specific configuration files for demos, tests and the code base. PyLint is part of the automatic testing pipeline. The warning log can be viewed online by selecting a Tests job and expanding the pylint output.

Docstrings

The API documentation for ΦFlow is generated using pdoc. We use Google style docstrings with Markdown formatting.

"""
Function description.

*Note in italic.*

Example:
    
    ```python
    def python_example()
    ```

Args:
    arg1: Description.
        Indentation for multi-line description.

Returns:
    Single output. For multi-output use same format as for args.
"""

Docstrings for variables are located directly below the public declaration.

variable: type = value
""" Docstring for the variable. """

Additional style choices

  • No line length limit; long lines are allowed as long as the code is easy to understand.
  • Code comments should only describe information that is not obvious from the code. They should be used sparingly as the code should be understandable by itself. For documentation, use docstrings instead. Code comments that explain a single line of code should go in the same line as the code they refer to, if possible.
  • Code comments that describe multiple lines precede the block and have the format # --- Comment ---.
  • Avoid empty lines inside of methods. To separate code blocks use multi-line comments as described above.
  • Use the apostrophe character ' to enclose strings that affect the program / are not displayed to the user. Use quotes for text such as warnings.