Contributing

The workflow for Cartridge contributors is different from that for Cartridge users. It implies building the project from source (documentation, Web UI) and running tests.

Submitting a pull request

  1. Fork and clone the repository.

  2. Build it and run it.

  3. Make a change, add tests, and make sure they still pass.

  4. Commit the changes and push them to your fork.

  5. Submit a pull request.

Here are a few things you can do that will increase the likelihood of your pull request being accepted:

  • Describe what you do in the pull request description, and why you do it.

  • Add an auto-test that covers your changes.

  • Keep your change as focused as possible. One scope – one pull request.

  • Write a good commit message.

See other related resources:

Building from source

The fastest way to build the project is to skip building the Web UI:

CMAKE_DUMMY_WEBUI=true tarantoolctl rocks make

But if you want to build the frontend too, you’ll also need nodejs >= 12 and npm >= 6, see instructions here.

Documentation is generated from source code, but only if the ldoc and sphinx tools are installed:

pip install -r rst/requirements.txt
tarantoolctl rocks install ldoc --server=https://tarantool.github.io/LDoc/
tarantoolctl rocks make

Running a demo cluster

There are several example entry points which are mostly used for testing, but can also be useful for demo purposes or experiments:

cartridge start
cartridge replicasets setup --bootstrap-vshard

# or select a specific entry point
# cartridge start --script ./test/entrypoint/srv_vshardless.lua

It can be accessed through the Web UI (http://localhost:8081) or via the binary protocol:

tarantoolctl connect admin@localhost:3301

# or via console socket
# tarantoolctl connect unix/:./tmp/run/cartridge.srv-1.control

If you also need the stateful failover mode, launch an external state provider – stateboard:

cartridge start --stateboard

And set failover parameters according to instances.yml. The defaults are:

  • State provider URI: localhost:4401;

  • Password: qwerty.

For more details about cartridge-cli, see its usage.

Running tests

# Backend
tarantoolctl rocks install luacheck
tarantoolctl rocks install luatest 0.5.7
.rocks/bin/luacheck .
.rocks/bin/luatest -v

# Frontend
npm install cypress@7.7.0
./frontend-test.sh
./cypress-test.sh

# Collect coverage
tarantoolctl rocks install luacov
tarantoolctl rocks install luacov-console
.rocks/bin/luatest -v --coverage
.rocks/bin/luacov-console `pwd`
.rocks/bin/luacov-console -s

Find more about testing tools here:

Updating auto-generated sources

If the GraphQL API is changed, the doc/schema.graphql should be updated:

npm install graphql-cli@3.0.14
./fetch-schema.sh

If you face some issues with script run, e.g. doc/schema.graphql: No such file or directory, try next:

npm audit fix --force

If the UML diagrams at rst/uml are changed, corresponding images should be updated. Install PlantUML:

sudo apt install plantuml
# OR
sudo brew install plantuml

And then just run the script:

cmake -P rst/BuildUML.cmake

Cypress tests imply snapshot testing. It compares WebUI images visually. In order to update reference snapshots, run:

./cypress-test.sh --env failOnSnapshotDiff=false