Developers Guide

Developers Guide Contents:

Installing QATrack+ For Development

Due to the huge volume of tutorials already written on developing software using Python, Django, and git, only a brief high level overview of getting started developing for the QATrack+ project will be given here. That said, there are lots of steps involved which can be intimidating to newcomers (especially git!). Try not to get discouraged and if you get stuck on anything or have questions about using git or contributing code then please post to the mailing list so we can help you out!

In order to develop for QATrack+ you first need to make sure you have a few requirements installed.

Python 3.6+

QATrack+ is developed using Python 3 (Python 3.6-3.9). Depending on your operating system, Python 3 may already be installed but if not you can find instructions for installing the proper version on https://python.org.

Git

QATrack+ uses the git version control system. While it is possible to download and modify QATrack+ without git, if you want to contribute code back to the QATrack+ project, or keep track of your changes, you will need to learn about git.

You can download and install git from https://git-scm.com. After you have git installed it is recommended you go through a git tutorial to learn about git branches, commiting code and pull requests. There are many tutorials available online including a tutorial by the Django team as well as a tutorial on and GitHub.

GitHub

The QATrack+ project currently uses GitHub for hosting its source code repository. In general, to contribute code to QATrack+ you will need to create a fork of QATrack+ on GitHub, make your changes, then make a pull request to the main QATrack+ project.

Creating a fork of QATrack+

Creating a fork of QATrack+ is explained in the GitHub documentation.

Cloning your fork to your local system

Once you have created a fork of QATrack+ on GitHub, you will want to download your fork to your local system to work on. This can either be done using the command line or one of the graphical git apps that are available. This page assumes you are using bash on linux or the Git Bash shell on Windows.

Setting up your development environment

In order to keep your QATrack+ development environment separate from your system Python installation, you will want to set up a virtual environment to install QATrack+’s Python dependencies in it. Using the command line change to the directory where you installed QATrack+, create a new virtual environment, and activate the virtual environment:

cd /path/to/qatrackplus
python3 -m venv env
source env/bin/activate

Then install the development libraries:

pip install -r requirements/dev.txt

Creating your development database

Rather than using a full blown database server for development work, You can use Sqlite3 which is included with Python.

Once you have the requirements installed, copy the debug local_settings.py file from the deploy subdirectory and then create your database:

cp deploy/dev/local_settings.dev.py qatrack/local_settings.py
mkdir db
python manage.py migrate
python manage.py createcachetable

this will put a database called default.db in the db subdirectory.

Running the development server

After the database is created, create a super user so you can log into QATrack+:

python manage.py createsuperuser

and then run the development server:

python manage.py runserver

Once the development server is running you should be able to visit http://127.0.0.1/ in your browser and log into QATrack+.

Next Steps

Now that you have the development server running, you are ready to begin modifying the code! If you have never used Django before it is highly recommended that you go through the official Django tutorial which is an excellent introduction to writing Django applications.

Once you are happy with your modifications, commit them to your source code repository, push your changes back to your online repository and make a pull request! If those terms mean nothing to you…read a git tutorial!

QATrack+ Development Guidelines

The following lists some guidelines to keep in mind when developing for QATrack+.

Internationalization & Translation

Please mark all strings and templates in QATrack+ for translation. This will allow for QATrack+ to be made avaialable in multiple languages. For discussion of how to mark templates and strings for translation please read the Django docs on translation.

Tool Tips And User Hints

Where possible all links, buttons and other “actionable” items should have a tooltip (via a title attribute or using one of the bootstrap tool tip libraries) which provides a concise description of what clicking the item will do. For example:

<a class="..."
    title="Click this link to perform XYZ"
    href="..."
>
    Foo
</a>

Other areas where tooltips are very useful is e.g. badges and labels where wording is abbreviated for display. For example:

<i class="fa fa-badge" title="There are 7 widgets for review">7<i>

<span title="This X has Y and Z for T">Foo baz qux</span>

Formatting & Style Guide

General formatting

In general, any code you write should be PEP 8 compatible with a few exceptions. It is highly recommended that you use flake8 to check your code for pep8 violations. A QATrack+ flake8 config file is included with QATrack+, to view any flake8 violations run:

make flake8
# or
flake8 .

You may also want to use yapf which can automatically format your code to conform with QATrack+’s style guide. A yapf configuration sections is included in the setup.cfg file. To run yapf:

make yapf

Import Order

Imports in your Python code should be split in three sections:

  1. Standard library imports
  2. Third party imports
  3. QATrack+ specific imports

and each section should be in alphabetical order. For example:

import math
import re
import sys

from django.apps import apps
from django.conf import settings
from django.contrib.auth.models import Group, User
from django.contrib.contenttypes.fields import (
    GenericForeignKey,
    GenericRelation,
)
from django_comments.models import Comment
import matplotlib
from matplotlib.backends.backend_agg import FigureCanvasAgg
import numpy
import scipy

from qatrack.qa import utils
from qatrack.units.models import Unit

isort is a simple tool for automatically ordering your imports and an isort configuration is included in the setup.cfg file.

Indentation

Python code for QATrack+ use 4 spaces for indentation. Django templates (and other html files) should use 2 spaces for indentation. Javascript code should use 4 spaces for indentation.

Running The Test Suite

Once you have QATrack+ and its dependencies installed you can run the test suite from the root QATrack+ directory using the py.test command:

./qatrackplus> py.test
Test session starts (platform: linux, Python 3.6.5, pytest 3.5.0, pytest-sugar 0.9.1)
Django settings: qatrack.settings (from ini file)
rootdir: /home/randlet/projects/qatrack/qatrackplus, inifile: pytest.ini
plugins: sugar-0.9.1, django-3.1.2, cov-2.5.1

qatrack/accounts/tests.py ✓✓✓

For more information on using py.test, refer to the py.test documentation.

Important

All new code you write should have tests written for it. Any non trivial code you wish to contribute back to QATrack+ will require you to write tests for the code providing as high a code coverage as possible. You can measure code coverage in the following way:

make cover

Writing Documentation

As well as writing tests for your new code, it will be extremely helpful for you to include documenation for the features you have built. The documentation for QATrack+ is located in the docs/ folder and is seperated into the following sections:

  1. User guide: Documentation for normal users of the QATrack+ installation.
  2. Admin guide: Documentation for users of QATrack+ who are responsible for configuring and maintaining Test Lists, Units etc.
  3. Tutorials: Complete examples of how to make use of QATrack+ features.
  4. Install: Documentation for the people responsible for installing, upgrading, and otherwise maintaining the QATrack+ server.
  5. Developers guide: You are reading it :)

Please browse through the docs and decide where is the most appropriate place to document your new feature.

While writing documentation, you can view the documentation locally in your web browser (at http://127.0.0.1:8008) by running one of the following commands:

make docs-autobuild
# -or-
sphinx-autobuild docs docs/_build/html -p 8008

I’m not a developer, how can I help out?

Not everyone has development experience or the desire to contribute code to QATrack+ but still wants to help the project out. Here are a couple of ways that you can contribute to the QATrack+ project without doing any software development:

  • Translations: Starting in QATrack+ v3.1.0 (sorry this didn’t happen yet), QATrack+ will have the infrastructure in place to support languages other than English. We will be making translation files available so that the community can create translation files for their native languages. Please get in touch with randy@multileaf.ca if you are able to help out with this task!
  • Tutorials: Tutorials are a great way for newcomers to learn their way around QATrack+. If you have an idea for a tutorial, we would love to include it in our tutorials section!
  • Mailing List: QATrack+ has a mailing list which QATrack+ users and administrators may find useful for getting support and discussing bugs and/or features. Join the list and chime in!
  • Spread the word: The QATrack+ community has grown primarily through word of mouth. Please let others know about QATrack+ when discussing QA/QC software :)
  • Other: Have any ideas for acquiring development funding for the QATrack+ project? We’d love to hear them!