CONTRIBUTING.md

Contributing guidelines

How to contribute?

This project is still in its very early stage. Until it reaches release 1.0, please do not send contributions as they will probably slow us down more than anything. Before the 1.0 release, files will be cleaned up, moved around and refactored. Until then it will be quite messy because of very frequent substantial changes.

After release 1.0, contributions will be more than welcome though!

Tools you need

Git Large File Storage (LFS)

As this project uses Git LFS to store large files, it requires Git LFS to be available on the system cloning this repository.

brew install git-lfs
git lfs install
# *Then*, run `git pull`.

Docker + Docker Compose

If you plan on running integration tests, you will need both Docker and Docker Compose on your machine. Here are the official docs for installing both of them:

• Install Docker
• Install Docker Compose

Or, if you’re running Linux (not macOS), you can simply run curl -L https://get.docker.com | sh.

task

Instead of using GNU Make, we are using Task for its simplicity and flexibility. You can find installation instructions on taskfile.dev/installation, or just run the folowing on macOS:

brew install go-task

To list all available commands, use:

task -a --sort none

Updating dependencies

task update

Testing

After you have setup your environment to run smoke tests and integration tests, you can run all of them in a single command using:

task test

This has the added benefit of updating the version of Rust used to run the tests in README.md.

Smoke testing

task smoke-test

As explained in ADR: Write tests with the Gherkin syntax, we are using Gherkin and Cucumber to run the tests. Therefore, you won't be able to filter tests using cargo test. To do so, add a @testing tag to a Feature, Rule or Scenario (non-exhaustive) and then use task smoke-test -- --tags '@testing' to run only matching Scenarios.

Integration testing

Installing dependencies

For integration tests, we use Step CI. To install it, follow instructions at Getting started | Step CI Docs or just run the following command if you don't have an exotic setup:

npm install -g stepci

Running tests

Then, run the tests using:

task integration-test -- --server=local

If a test fails, Step CI will automatically print some additional information to help you debug the issue. We also print container logs so you can see internal errors.

Tip

Step CI collects analytics when it's used, which is fine, but it also means stepci will fail if it can't reach the analytics server. If you need to run tests offline, run export STEPCI_DISABLE_ANALYTICS=true before running the tests.

Building the Docker image

To build the Docker image, you can use the helper script (which builds the image as proseim/prose-pod-api:local):

task build-image [-- [--platform=TARGET_PLATFORM] [--profile=CARGO_PROFILE] [--help]]

If you don't set TARGET_PLATFORM, build-image will build proseim/prose-pod-api:local for your local platform. If you set TARGET_PLATFORM, build-image will build proseim/prose-pod-api:local for the desired platform. You can set PROSE_POD_API_IMAGE to override the final name of the image.

To build the API in debug mode (e.g. to use predictable data generators), you can use the --profile=dev argument:

task build-image -- [--platform=TARGET_PLATFORM] --profile=dev

Style

(This is a work in progress)

• Always parse user input (see Parse all user input · Issue #164 · prose-im/prose-pod-api). To make it easier, we use use validator + serdev to validate during deserialization. When you need this (i.e. when some wrapped type needs validation), derive serdev::Deserialize explicitly and do not use it. This makes intent clearer and helps spotting forgotten serde(validate = "Validate::validate"). More generally, always make serdev explicit when it is used; otherwise (e.g. for serialization) you can use it.
• Derive Debug everywhere.
• Derive Clone only when cloning is cheap.