Developer Contribution
======================

You can join (and Star!) us on `GitHub <https://github.com/Actable-AI/actableai-lib>`__!

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.

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

   .. code:: bash

      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.

#. **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:

.. code-block:: shell

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

Code Style
----------

In general, we follow the `Google style guide <https://google.github.io/styleguide/>`__ 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 <https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html>`__.
The following code snippet demonstrates the canonical Actable AI pydoc formatting:

.. code-block:: python

    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 <https://github.com/Actable-AI/actableai-app/blob/master/requirements_linters.txt>`_ first with:

.. code-block:: shell

  pip install -r requirements_linters.txt

You can then run the following locally:

.. code-block:: shell

    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:

.. code-block:: python

    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:

.. code-block:: python

    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.