Isabl Docs
Search…
Contributing Guide
⏱ tutorial time: 20 minutes
This tutorial will help you set up a full Development environment with all components of the isabl infrastructure.
πŸ“˜ Contributions are welcome, and they are greatly appreciated! Every little bit helps, and credit will always be given. isabl could always use more documentation, whether as part of the README, in doc-strings, or even on the web in blog posts articles, and such. Also, bet you've read the Zen Of Python.

Isabl API

    1.
    Clone locally:
    1
    git clone [email protected]:isabl-io/api.git
    2
    cd api
    Copied!
    2.
    Build containers:
    1
    docker-compose build
    Copied!
    3.
    Run tests using tox:
    1
    docker-compose run --rm django tox
    Copied!
    Or run pytest, pylint or pydocstyle individually:
    1
    docker-compose run --rm django pytest --ds example.settings --cov=isabl_api
    2
    docker-compose run --rm django pylint isabl_api
    3
    docker-compose run --rm django pydocstyle isabl_api
    Copied!

Create a superuser

Create a superuser with username and password set to admin (we will need it later):
1
docker-compose run --rm django python manage.py createsuperuser --email [email protected] --username admin
Copied!
Now you can login in the frontend at http://localhost:8000 (there won't be much to see). An easy way to create objects is to run the client tests.

Coverage report

Since tests were run inside a container, we need to combine the coverages to see the html report:
1
alias opencov="mv .coverage .coverage.tmp && coverage combine && coverage html && open htmlcov/index.html"
2
pip install coverage && opencov
Copied!

Isabl CLI

    1.
    Clone locally:
    1
    git clone [email protected]:isabl-io/cli.git
    2
    cd cli
    Copied!
    2.
    Install with pip, it is strongly recommended to install in a virtual environment:
    1
    pip install -r requirements.txt
    Copied!
    3.
    Run tests using tox, make sure you created the admin user:
    1
    tox
    Copied!
    Or run pytest, pylint or pydocstyle individually:
    1
    py.test tests/ --cov=isabl_cli -s
    2
    pylint isabl_cli
    3
    pydocstyle isabl_cli
    Copied!
Note: if your changes depend on a particular branch of Isabl API, make sure both Isabl CLI and Isabl API branches are called the same so that the travis configuration can pick that up.

Isabl Web

    1.
    Clone locally:
    1
    git clone [email protected]:isabl-io/web.git
    2
    cd web
    Copied!
    2.
    Install yarn:
    1
    brew install yarn --without-node
    Copied!
    3.
    Install dependencies:
    1
    yarn install
    Copied!
    4.
    Start the react development server:
    1
    yarn serve
    Copied!
    Important! export FRONTEND_URL=localhost:8080 before running docker-compose up in the api repository, note that the port may vary.

Documentation

Simply create a PR in github:
1
git clone [email protected]:isabl-io/docs.git
Copied!

Contribute with Github

    1.
    Create a branch for local development and get ready to make changes locally:
    1
    git pull
    2
    git checkout -b name-of-your-bugfix-or-feature
    Copied!
    2.
    Commit your changes and push your branch to GitHub (see the emoji reference):
    1
    git add .
    2
    git config commit.template .gitmessage
    3
    git commit -m ":emoji: your short and nice description"
    4
    git push origin name-of-your-bugfix-or-feature
    Copied!
    3.
    Create a test in:
    1
    tests/
    Copied!
    4.
    Submit a pull request through the GitHub website.

Formatting projects

Python Projects are formatted with black. Is required for api, cli and apps, simply run:
1
pip install black && black .
Copied!
Project web is formatted following the Vue style guide. For this one, simply run:
1
yarn lint
Copied!

Bumping version of PyPi

Following the semantic versioning guidelines and update the VERSION file before creating a PR, for instance:
1
echo v0.1.0 > isabl_api/VERSION
2
git add isabl_api/VERSION
3
git commit -m ":gem: bump to version 0.1.0"
Copied!

Emoji reference

We use emojis to quickly categorize commits and pull requests. These are some common type of changes we use but feel free to ignore the conventions:
emoji
name
type of change
πŸš€
rocket
new feature
πŸ›
bug
bug fix
πŸ“
memo
changes to documentation
🎨
art
formatting no code change
πŸ”§
wrench
refactoring production code
βœ…
white_check_mark
adding/editing test logic
πŸ‘•
shirt
no production code change
πŸ’Ž
gem
bump to new version
Tip: To insert an emoji in mac type control+cmd+space. Alternative, type the emoji's name within two semicolons (e.g. :rocket:).
Last modified 2yr ago