Contributing to the project

Contributing to the opsdroid ecosystem is strongly encouraged and every little bit counts!

Things you can help with: - Documentation - Localization - Creating new modules - Issues - Squashing bugs - Enhance opsdroid

If you need help or if you are unsure about something join our gitter channel and ask away! We are more than happy to help you.

Workflow

All contributors to the project, including the project founder jacobtomlinson, contribute using the following process:

Fork the main project to your own account
Work on your changes on a feature branch
Create a pull request back to the main project
Tests and test coverage will be checked automatically
A project maintainer will review and merge the pull request

Developing

# clone the repo
git clone https://github.com/opsdroid/opsdroid.git
cd opsdroid

# install the project in "editable" mode
pip install -e .

# run opsdroid
python -m opsdroid

Running the tests

# install test runner
pip install -U tox

# run tests
tox

Developing in containers

Developing in containers can be a great way to ensure that opsdroid will run in a clean python environment and that all dependencies are captured.

# build the container
docker build -t opsdroid/opsdroid:myfeature .

# run opsdroid
docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature

Running the tests

# run tests
docker run --rm -ti -v $(pwd):/usr/src/app opsdroid/opsdroid:myfeature tox

Documentation

More documentation is always appreciated and it's something that you can contribute to from the GitHub web interface. This might be a great start point if you are new to Open Source and GitHub!

Things that we need help with:

More documentation. Something that you think is unclear?
More examples on how to use opsdroid
More Tutorials
Typos/Grammar check
Blog posts, articles, etc
Any issue marked with the documentation tag

Localization

Opsdroid runs by default in English, but it can be translated to your local language. In order to achieve it, gettext and babel are used.

To mark a string as translatable, just call the special _ function:

txt = 'hello {}'.format(name)  # this is NOT translatable
txt = _('hello {}').format(name)  # but now it's translatable! 🎉

When some new translatable strings are added, you must extract them to a non versioned pot file with:

python setup.py extract_messages

Then, update all existing language po files from the extracted pot file with the command:

python setup.py update_catalog

Now, you can translate editing manually or with Poedit the po files in locale/<lang>/LC_MESSAGES/opsdroid.po. Those files contain the real translations and are versioned.

After you made a change in any po file, in order to view the changes in opsdroid, you should compile them to mo binary files, the format readed by python gettext:

python setup.py compile_catalog

Starting a new language

If your language is not in the locale folder, you can initialize it. You will need the ISO 639-1 code of the language. For example, in order to start a new Esperanto translation:

python setup.py init_catalog -l eo

Then you can translate it in locale/eo/LC_MESSAGES/opsdroid.po, then compile it, etc.

Creating New Modules

Opsdroid is an open source chatbot framework. It is designed to be extendable, scalable and simple. It comes with a few official modules that can be found in the Opsdroid GitHub account.

If you love a particular platform and wish to use opsdroid with it or if you want opsdroid to interact with something in a certain way you can create your own modules and extend the functionality of opsdroid.

If you don't know where to start, make sure to check the tutorials and read the documentation. Remember that you can also ask for help in our gitter channel

Issues

You can help us by reporting new issues or by fixing existing issues.

If you find any part of opsdroid that's acting odd it would be great if you take the time to create a new issue. That will help us keep opsdroid free of any bugs.

We try to tackle issues as fast as possible, but help would be greatly appreciated. To get started, simply follow the workflow guidelines and developing instructions.

Quick Links:

Don't forget, you can always help with the modules found in opsdroid repository.