Contributing Guide

Contributing to Alcali is fairly easy. This document shows you how to get started

General

Please ensure that any changes you make are in accordance with the Coding Guidelines of this repo.

Just use Black to validate your python code.

Install a dev environment

First fork the repository and install your fork locally.

git clone git@github.com:<YOUR USERNAME>/alcali.git
cd alcali

Alcali use Vuejs for the frontend and Django for the backend.

Frontend dev

Add a pre-commit hook to build the project:

cat <<-EOF>.git/hooks/pre-commit
#!/bin/sh

echo "building frontend ..."
npm run build
git add dist/*
EOF

Make it executable:

chmod +x .git/hooks/pre-commit

Install the Vue CLI:

npm install -g @vue/cli
# OR
yarn global add @vue/cli

install js deps:

npm install
# OR
yarn install

and run your build locally:

npm run serve -- --port 8001

You will also need a backend running in another terminal.

Backend dev

docker-compose up --build --force-recreate --renew-anon-volumes --scale minion=2

Documentation

To contribute to the documentation, you'll need to install the python requirements, preferably in a virtualenv:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/docs.txt

And build it locally:

cd docs
mkdocs serve -a 127.0.0.1:8003

Submitting changes

Check out a new branch based and name it to what you intend to do:

$ git checkout -b BRANCH_NAME feature/fooBar

If you get an error, you may need to fetch fooBar first by using

$ git remote update && git fetch

Use one branch per fix / feature

Commit your changes

  • Please provide a git message that explains what you've done
  • Please make sure your commits follow the conventions
  • Commit to the forked repository
$ git commit -am 'Add some fooBar'

Push to the branch

$ git push origin feature/fooBar

Make a pull request - Make sure you send the PR to the fooBar branch - Travis CI is watching you!

If you follow these instructions, your PR will land pretty safely in the main repo!