Contributing

It is recommended to contribute to ESBMC-AI directly, especially if the feature would improve ESBMC-AI directly. When contributing you can create a pull request, and after all the issues are resolved, and it passes the code-review, it will be merged. Try to submit patches that follow the following rules:

Keep the coding style consistent. Use the Black code formatter, it is specified as a development dependency, so it will be installed automatically.
Document the contributions you make accordingly, if it is a new feature, please add the correct documentation. Keep the righting style professional when writing documentation.
Include comments and function doc-strings to all public functions made.
Make sure to update tests as appropriate.

To learn more about the code-base of ESBMC-AI, you can read so in the Architecture.

Source Code Setup

In order to begin contributing to ESBMC-AI’s source code, please follow the steps:

Fork the repo

Begin working

ESBMC-AI is developed using the Hatch project management. So initializing an environment in it would automatically install all the dependencies, allowing the development to begin relatively painlessly. Initialize the development environment:

hatch shell

Now you can write you code and run the esbmc_ai module directly or using the helper script ./esbmc-ai.

Submit a pull request in the ESBMC-AI repo

If you aren’t sure if this feature wil be accepted into ESBMC-AI, you can create one as a draft where you describe the feature. If it gets rejected without any comments you can turn it into an addon.

Addon Development

Important

Before developing an addon, create a draft PR to discuss if a topic should be contributed directly into ESBMC-AI. Contributing directly to ESBMC-AI has benefits vs. addons.

Ease-of-use: Avoids the need to separatley install the addon, making it more widely used in ESBMC-AI.
Credit: If a major contribution is made, you will be added in the contributors credit page for ESBMC-AI (when we make one).
Version Compatibility: Features in the main code-base will work with future versions, as future compatibility will be ensured. With addons this is not guaranteed, and it is solely up to the addon developer to ensure this compaitbility.

If a feature would not be suitable as in the ESBMC-AI Platform, you can create an addon for it. This can happen if a PR is denied. Creating an addon is a relatively easy experience. The following steps can be used to begin development:

Enabling Addon Development Mode

Enable the dev_mode flag in the config. This will make ESBMC-AI search for modules in your current directory in addition to the system path which is by default.

Addon Template

Download the addon template and begin developing using it.

In order for ESBMC-AI to detect the addon, export it by specifying it in the __all__ variable in __init__.py. In the config used for ESBMC-AI, specify the import path to that addon as an entry to the addon_modules config field.

Example

Assume you are developing an addon called “metanoia” with the following folder structure:

pyproject.toml

<li class="hx-flex hx-list-none">
  <span class="hx-inline-flex hx-cursor-default hx-items-center hx-py-1"><svg width=1em xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/></svg><span class="ltr:hx-ml-1 rtl:hx-mr-1">config.toml</span>
  </span>
</li>

__init__.py

    <li class="hx-flex hx-list-none">
      <span class="hx-inline-flex hx-cursor-default hx-items-center hx-py-1"><svg width=1em xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"/></svg><span class="ltr:hx-ml-1 rtl:hx-mr-1">metanoia.py</span>
      </span>
    </li>

- custom_fix.py
- - pytest_verifier.py

In order for ESBMC-AI to detect the addon, you can export all the relevant classes by assigning them to the __all__ variable in the __init__.py file that will be specified in the ESBMC-AI config:

metanoia/__init__.py

from .chat_commands.custom_fix import CustomFix
from .verifiers.pytest_verifier import PyTestVerifier

__all__ = [
    "CustomFix",
    "PyTestVerifier",
]

Configuring ESBMC-AI Addons