Contributing

The Kotti project can use your help in developing the software, requesting features, reporting bugs, writing developer and end-user documentation – the usual assortment for an open source project.

Please devote some of your time to the project.

Contributing to the Code Base

To contribute to Kotti itself, and to test and run against the master branch (the current development code base), first create an account on GitHub if you don’t have one. Fork Kotti to your github account, and follow the usual steps to get a local clone, with origin as your fork, and with upstream as the Kotti/Kotti repo. Then, you will be able to make branches for contributing, etc. Please read the docs on GitHub if you are new to development, but the steps, after you have your own fork, would be something like this:

git clone https://github.com/your_github/Kotti.git

cd Kotti

git remote add upstream git://github.com/Kotti/Kotti.git

Now you should be set up to make branches for this and that, doing a pull request from a branch, and the usual git procedures. You may wish to read the GitHub fork-a-repo help.

To run and develop within your clone, do these steps:

python3 -m venv .

bin/pip install -e ".[testing]"

This will create a new virtualenv “in place” and do the python develop steps to use the Kotti code in the repo.

Run bin/pip install kotti_someaddon, and add a kotti_someaddon entry to app.ini, as you would do normally, to use add-ons.

You may wish to learn about the virtualenvwrapper system if you have several add-ons you develop or contribute to. For example, you could have a development area devoted to Kotti work, ~/kotti, and in there you could have clones of repos for various add-ons. And for each, or in some combination, you would use virtualenvwrapper to create virtualenvs for working with individual add-ons or Kotti-based projects. virtualenvwrapper will set these virtualenvs up, by default, in a directory within your home directory. With this setup, you can do workon kotti_this and workon kotti_that to switch between different virtualenvs. This is handy for maintaining different sets of dependencies and customizations, and for staying organized.

Contributing to Developer Docs

Kotti uses the Sphinx tool, using reStructuredText to write documents, stored in docs/ in a directory structure with .rst files. Use the normal git procedures for first making a branch, e.g., navigation_docs, then after making changes, commit, push to this branch on your fork, and do a pull request from there, just as you would for contributing to the code base.

In your Kotti clone you can install the requirements for building and viewing the documents locally:

python setup.py docs

cd docs/

make html

Then you can check the .html files in the _build/ directory locally, before you do an actual pull request.

The rendered docs are built and hosted on readthedocs.org.

Contributing to User Docs

The Kotti User Manual also uses Sphinx and reStructuredText, but there is a bit more to the procedure, because several additional tools are used. Selenium is used for making screen captures, and thereby helps to actually test Kotti in the process. blockdiag is used to make flow charts and diagrams interjected into the docs.

Please follow the readme instructions in the Kotti User Manual repo to get set up for contributing to the user manual. Of course, you can do pull requests that change only the text, but please get set up for working with graphics also, because this is a way to do the important task of keeping Kotti user docs up-to-date, guaranteed to have graphics in sync with the latest Kotti version.

The rendered docs are built and hosted on readthedocs.org.