Developer Contribution

You can join (and Star!) us on GitHub!

Contributing to Actable AI

We welcome all forms of contributions to Actable AI, including but not limited to:

  • Code reviewing of patches and pull requests (PRs).

  • Pushing patches.

  • Documentation and examples.

  • Community participation in forums and issues.

  • Code readability and code comments to improve readability.

  • Test cases to make the codebase more robust.

  • Tutorials, blog posts, and talks that promote the project.

What can I work on?

We use GitHub to track issues, feature requests, and bugs. This makes it easy to view any issues or requests that could be resolved.

Setting up your development environment

To edit the Actable source code, you’ll want to checkout the repository and build Actable AI from source. Follow the instructions listed in the GitHub repository to build a local copy of Actable AI and easily make changes.

Submitting and merging a contribution

There are a couple steps to merge a contribution.

  1. First, merge the most recent version of master into your development branch:

    git remote add upstream https://github.com/Actable-AI/actableai-app.git
git pull . upstream/master

#. Ensure that all existing tests and linters pass. Run setup_hooks.sh to create a git hook that will run the linter before you push your changes.

#. If introducing a new feature or patching a bug, be sure to add new test cases in the relevant file.

  1. Document the code. The code needs to be well-explained and documented using comments in the code itself, and at least one usage example should also be provided (if applicable).

#. Respond to, and address, any comments in your pull request. During the review process, you may need to resolve merge conflicts arising due to other changes. To resolve merge conflicts, run git pull . upstream/master on your branch

Note

Please do not use rebase, as it is less friendly to the GitHub review tool given that all commits will be squashed on merge.

#. Reviewers will then merge and approve the pull request. Be sure to ping them if the pull request is getting stale.

Pull Request (PR) Review Process

  • PRs will be given assignees shortly after they are submitted.

  • Assignees of PRs will actively engage with contributors to merge the PR.

  • Please actively ping assignees after you address your comments to ensure that the PR does not get stale!

Testing

Even though we have hooks to run unit tests automatically for each pull request, we recommend that you run unit tests locally beforehand. This reduces reviewers’ burden and speeds up the review process.

If you are running tests for the first time, you can install the required dependencies with:

pip install -r python/requirements.txt
pytest superset/

Code Style

In general, we follow the Google style guide for code in Python. However, it is more important for code to be in a locally consistent style than to strictly follow the guidelines. Whenever in doubt, follow the local code style of the component being modified.

For documentation in Python, we follow a subset of the Google pydoc format. The following code snippet demonstrates the canonical Actable AI pydoc formatting:

def canonical_doc_style(param1: int, param2: str) -> bool:
    """First sentence MUST be inline with the quotes and fit on one line.

    Additional explanatory text can be added in paragraphs such as this one.
    Do not introduce multi-line first sentences.

    Examples:
        >>> # Provide code examples as possible.
        >>> canonical_doc_style(41, "hello")
        True

        >>> # A second example.
        >>> canonical_doc_style(72, "goodbye")
        False

    Args:
        param1: The first parameter. Do not include the types in the
            docstring (they should be defined only in the signature).
            Multi-line parameter docs should be indented by four spaces.
        param2: The second parameter.

    Returns:
        The return value. Do not include types here.
    """

Lint and Formatting

We also have tests for code formatting and linting that need to pass before the code can be merged.

For Python formatting, install the required dependencies first with:

pip install -r requirements_linters.txt

You can then run the following locally:

scripts/format.sh

Other recommendations:

In Python APIs, consider forcing the use of keyword arguments (kwargs) instead of positional arguments (using the * operator). This is because it is easier to maintain backwards compatibility with kwargs than positional arguments.

For example, suppose you needed to deprecate “opt1” below; it is easier with forced kwargs:

def foo_bar(file, *, opt1=x, opt2=y)
    pass

For callback APIs, consider adding a **kwargs placeholder as a “forward compatibility placeholder” in case more arguments need to be passed to the callback in the future. For example:

def tune_user_callback(model, score, **future_kwargs):
    pass

Becoming a Reviewer

We identify reviewers from active contributors. Reviewers are individuals who not only actively contribute to the project but are also willing to participate in the code review of new contributions. A pull request to the project has to be reviewed by at least one reviewer in order to be merged. There is currently no formal process for reviewer selection, but any active contributors to Actable AI will be approached by current reviewers.