Contribute

Kiwi TCMS team welcomes and appreciates any kind of contribution from you in order to make Kiwi TCMS better and better. Anyone who is interested in Kiwi TCMS is able to contribute in various areas, whatever you are a good and experienced developer, documentation writer or even a normal user.

Get source code

The Kiwi TCMS source code is available at: https://github.com/kiwitcms/Kiwi:

git clone https://github.com/kiwitcms/Kiwi.git

Install Python 3

Kiwi TCMS is a Python 3 project! On CentOS 7 this is available via SoftwareCollections.org. All further instructions assume that you have Python 3 enabled. If you are using software collections then execute:

scl enable rh-python36 /bin/bash

If you are using a different Linux distribution then consult its documentation for more details on how to install and enable Python 3!

Note

At the time of writing Kiwi TCMS has been tested with Python 3.6. You can always consult Dockerfile to find out the latest version which we use!

Setup virtualenv

Create a virtual environment for Kiwi TCMS:

virtualenv ~/virtualenvs/kiwi

Dependencies

First install RPM packages which are needed to compile some of the Python dependencies:

sudo yum install gcc python-devel mariadb-devel libxml2-devel libxslt-devel graphviz

Note

Graphviz is only used to build model diagrams from source code!

Then install dependencies for development:

. ~/virtualenvs/kiwi/bin/activate
pip install -r requirements/mariadb.txt
pip install -r requirements/devel.txt

Note

Alternatively you can use requirements/postgres.txt for PostgreSQL!

The user interface needs the PatternFly library so:

npm install

inside the project directory.

Initialize database

Note

In development mode Kiwi TCMS is configured to use SQLite! You may want to adjust the database and/or other configuration settings. Override them in ./tcms/settings/devel.py if necessary.

Load database schema and create initial user:

./manage.py migrate
./manage.py createsuperuser

Let’s run Kiwi TCMS

You’re now ready to start the server:

./manage.py runserver

Now, open http://127.0.0.1:8000/ and should be presented with your brand new Kiwi TCMS homepage!

Testing

Automated test suite can be executed with the make check command. The following syntax is supported:

make check (uses SQlite)
TEST_DB=MySQL make check
TEST_DB=MariaDB make check
TEST_DB=Postgres make check
TEST_DB=all make check (will test on all DBs)

Note

If you want to execute testing against different DB engines on your local development environment make sure the respective DB engines are installed and configured! make check uses the configuration files under tcms/settings/test/. Make sure to edit them if necessary!

Security Issues

If you think that an issue with Kiwi TCMS may have security implications, please do not publically report it in the bug tracker. Instead ping us via email to coordinate the fix and disclosure of the issue!

Reporting General Issues

If you have any good idea, or catch a bug, please do create an issue at https://github.com/kiwitcms/Kiwi/issues!

Documentation

Documentation has been provided along with the source code within the docs/ directory and is built using Sphinx. All content is written in reStructuredText format. To build the docs:

$ cd docs/
$ make html

Translation

Kiwi TCMS is using Crowdin as our translation service. You can find the project at https://crowdin.com/project/kiwitcms. You need to register with Crowdin before you can work on any translations!

To request a new language be added to Kiwi TCMS please create an issue. In the description let us know your Crowdin username!

Before starting to translate please read the Starting Translation how-to and the Online Editor guide.

Note

All translations need to be proof-read before they are approved! If you do not have sufficient Crowdin permissions to do so let us know that you have some new translations that you’d like to be approved.

Making strings translatable

Before strings can be translated they need to be marked as translatable. This is done with the gettext() function or its shortcut _(). For templates {% load i18n %} at the top of the template and then use the {% trans %} template tag to mark strings as translatable! Please read Django’s Translation documentation if you are not sure what these functions are!

Warning

To update .po files once translatable strings have been changed or updated you have to execute the following command and commit the results in git:

./manage.py makemessages

At the moment there is no test for this because Django doesn’t make it easier to implement a quick test based on ‘git status’!

Note

To update .mo files once new translations have been added or updated you have to execute the following command and commit the results in git:

./manage.py compilemessages

There is also an automated test for this via make check-mo-files!