Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
250 lines (169 loc) · 8.69 KB

CONTRIBUTING.md

File metadata and controls

250 lines (169 loc) · 8.69 KB
Raw

Contributing to the project

Development

Development prerequisites

Before you can contribute to this project, you need to install and set up the following tools:

  • Rust: Install Rust through rustup, which you can get from the official Rust website. After installation, you can verify it by running cargo --version in your terminal.

  • Just: Install just, a command runner that simplifies project workflows. You can find the installation instructions in the official just documentation. After installation, you can verify it by running just --version in your terminal.

  • Mozilla SOPS: Install SOPS for managing encrypted environment variables. You can find the installation instructions in the official SOPS documentation. After installation, you can verify it by running sops --version in your terminal.

  • Age: Age is a simple, modern and secure file encryption tool, used by SOPS for encrypting secrets. You can install it from the official Age GitHub repository. After installation, you can verify it by running age --version in your terminal.

  • Docker: Install Docker from the official Docker website. After installation, you can verify it by running docker --version in your terminal.

Please ensure you have all these prerequisites in place before you start contributing to the project.

Tip

You can run just --list to see all available development tasks.

Rust workflow

Formatting

Code formatting is automatically enforced using rustfmt.

Warning

Automatic imports formatting require the use of nightly Rust toolchain.

just fmt

To check Rust code formatting without making changes, you can use:

just fmt-check

Linting

Code linting is automatically enforced using clippy.

In the CI pipeline, we use the following command to run the linter:

just check

Testing

Tip

Tests that require access to secrets should be run using the encrypted .env file. Refer to the CI Secrets section for more information.

To run the project unit tests, you can use the following command:

just test-unit

To run the project integration tests, you can use the following command:

just test-it

Git hooks

This project uses pre-commit to automatically run code formatting checks before commits are made. Git hooks help ensure code quality and consistency by automatically running the formatting tools whenever you commit changes.

Note

Git hooks are optional and opt-in. You can contribute to the project without installing them, but they provide a convenient way to automatically format your code before commits.

Prerequisites

Before setting up Git hooks, you need to install pre-commit. You can install it using your preferred package manager:

# Using pip
pip install pre-commit

# Using pacman (Arch Linux)
pacman -S pre-commit

# Using apt (Ubuntu/Debian)
apt-get install pre-commit

# Using Homebrew (macOS)
brew install pre-commit

Installing Git hooks

To install the pre-commit hooks for this project, run:

just install-git-hooks

This command will:

  1. Check if pre-commit is installed on your system
  2. Install the pre-commit hooks defined in .github/pre-commit-config.yaml

Removing Git hooks

If you need to remove the Git hooks, you can run:

just remove-git-hooks

Running hooks manually

You can also run the pre-commit hooks manually without making a commit:

# Run all hooks on all files
pre-commit run --all-files --config .github/pre-commit-config.yaml

# Run specific hook
pre-commit run format --config .github/pre-commit-config.yaml

Tip

If you need to commit changes without running the hooks (not recommended), you can use git commit --no-verify.

CI Secrets

In this project, we handle secrets through an encrypted .env file. This file holds various environment variables, encrypted using Mozilla SOPS, a secure tool for managing and storing secrets. We utilize Age, a simple, modern, and secure file encryption tool, as the encryption backend for SOPS. This method allows us to manage secrets without the need for contributors to access GitHub Actions secrets, offering a secure way to introduce new test credentials required by the tests.

Prerequisites

  1. Install Age and SOPS: Ensure you have both Age and SOPS installed on your machine. For more information refer to the Prerequisites section.

  2. Generate a new key pair: Generate a new key pair using the following command:

    age-keygen -o keys.txt

    This command generates a new key pair and saves it to the keys.txt file. This key pair is used to encrypt and decrypt the .env file.

    According to the SOPS documentation, by default SOPS will look for a <user-config-dir>/sops/age/keys.txt file under the user's configuration directory (e.g., $XDG_CONFIG_HOME/sops/age/keys.txt in Linux).

Running the tests

To run the tests, you need to decrypt the .env file using the sops exec-env command. This command decrypts the .env file and sets the environment variables for the command that follows it.

For example, to execute the project integration tests with the decrypted environment variables, you can use the following command:

sops exec-env .env "just test-it"

The command above assumes that a valid keys.txt file is present in the user's configuration directory.

Alternatively, if you have a different key file or location, you can specify it using the SOPS_AGE_KEY_FILE environment variable or passing the Age private key content directly to the sops exec-env command via the SOPS_AGE_KEY environment variable.

SOPS_AGE_KEY_FILE=/path/to/keys.txt sops exec-env .env "just test-it"

Adding new contributors public keys

In order to any new contributor to be able to decrypt the .env file, the file needs to be encrypted using their public key. To do so, we need to add the new contributor's public key as recipients to the .env file. To do so, you have to ask a project maintainer to encrypt the .env file using the new contributor's public key. To do so, run the following command:

sops --rotate --add-age <new-recipient-age-key> --in-place .env

The command above assumes that the .env file is already encrypted with the public keys of the project contributors, and the project maintainer has the private keys to decrypt the file.

Adding new secrets

Once your Age public key is associated with the .env file, you can add new secrets to the file. To do so, you can use the following command to add a new secret to the file:

sops --set '["<env-var-name>"] "<env-var-value>"' .env

Note that the env-var-name and env-var-value should be replaced with the name and value of the new environment variable you want to add to the .env file. If an environment variable with the same name already exists, the command will update the value of the existing environment variable.

Encrypting and decrypting the .env file

Warning

This procedure is completely discouraged due to the ⚠️risk of leaking sensitive information⚠️. Only project maintainers should encrypt and decrypt the .env file.

Refer to the Adding new contributors public keys or Adding new secrets sections for a safer way to manipulate the .env file.

To encrypt the .env file in-place, you can use the following command where <recipien-age-key> are the public keys of the different project contributors:

sops --encrypt --age <recipient-age-key>[,<recipient-age-key>,...] .env

Assuming that the .env file is encrypted with the public keys of the project contributors, and your private key is present in the keys.txt file, you can decrypt the .env file using the following command:

sops --decrypt .env

Both commands will print the decrypted content to the standard output. If you want to save the decrypted content to a file, you can redirect the output to a file, or use the --in-place flag to overwrite the file in-place.