Skip to main content

Contributing to Components

Resoto is comprised of multiple components, each of which is maintained as separate project:

The source code for Resoto lives in the someengineering/resoto repository on GitHub.

Authoring Changes

Contributions are made via pull requests to the GitHub repository. You will first need to fork the repository.

Pull requests should target a single component.

Prerequisites

note

On Apple Silicon (ARM) devices, like the M1 Macbooks, only versions of ArangoDB < 3.9 are supported. That is because ArangoDB 3.9+ is officially only available on x86 architecture and makes use of CPU instructions not emulated by MacOS' Rosetta 2.

There are unofficial ARM builds of ArangoDB, like e.g. programmador/arangodb but they have not been tested with Resoto.

Cloning the Repository

You will first need to fork the repository.

Then, creating a local clone of the repository is as simple as:

git clone https://github.com/<your_github_username>/resoto.git

This will create a directory named resoto in your current working directory.

Next, add a remote pointing to the upstream repository (as opposed to your fork) named upstream:

git remote add upstream https://github.com/someengineering/resoto.git

We will now create a new branch from main (it is recommended to give your branch a meaningful, descriptive name):

git checkout -b <branch_name> main

Setting Up a Virtual Environment

We recommend using a Python virtual environment.

A script is provided to simplify the process of configuring the virtual environment:

./setup_venv.sh --dev --path .

Activate the virtual environment:

source venv/bin/activate

Starting the Database

Start ArangoDB (using systemctl on Linux, by clicking the application icon in macOS, etc.). If you used Homebrew to install ArangoDB, run /usr/local/Cellar/arangodb/<VERSION>/sbin/arangod &.

Depending on the installation method used for ArangoDB, authentication may or may not be enabled on the built-in root user account. The installation process either prompted for the root password (Debian, Windows), configured a random password (Red Hat), or set the password to an empty string.

In order for resotocore to perform the required database setup and for tests to pass, authentication must be disabled or the password for root must be set to an empty string.

caution

This setup is for development only and should not be deployed in production environments.

Starting the Components

You can now start each of the Resoto components:

cd resotocore
python -m resotocore

Testing Your Changes

We use the pytest framework. Prior to submitting your changes for review, please verify that all existing tests pass and add test coverage for new code.

Lint and test your code:

tox

Pushing Your Changes

When you are ready to submit your changes for review, commit them to your local repository:

git commit

Then, push them to your fork:

git push --set-upstream origin <branch_name>

You can now submit your pull request on GitHub! You are welcome to open your pull request as a draft for early feedback and review. Be sure to follow the pull request template!

info

Pull request titles should follow the following format for correct parsing by the changelog generator script:

[<scope>][<type>] <description>
PlaceholderDescription
<scope>Affected/target component
<type>fix, feat, or chore
<description>Description of changes

However, do not worry too much about getting this right, as we will make any necessary adjustments prior to merging your changes.