Developers Guide

Note

Disclaimer: This guide was developed and tested on Ubuntu Linux. While the instructions should work on other operating systems, some commands, package names, or installation steps may differ. If you encounter issues on a different OS, please refer to the specific documentation for your platform or reach out to the community for assistance.

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!

Prerequisites

QATrack+ is developed using Python 3.12. We recommend using the latest stable version of Python 3.12 for the best development experience and compatibility.

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 GitHub.

GitHub Account

The QATrack+ project currently uses GitHub for hosting its source code repository. 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+ is explained in the GitHub documentation.

uv Package Manager

The QATrack+ project uses uv, a fast Python package manager. uv handles Python version management, virtual environments, and dependency management.

Install uv using the official installer (recommended):

# On Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Alternative method using pip
pip install uv

For other installation methods or troubleshooting, see the full installation guide at https://docs.astral.sh/uv/getting-started/installation/

Setting up your development environment

First create a fork of the QATrack+ repository on GitHub.

Then clone your fork to your local machine:

git clone https://github.com/YOUR_USERNAME/qatrackplus.git

Selecting an Editor or IDE

You can use a variety of tools to edit and work on the QATrack+ codebase. Some popular options include:

  • VS Code: A free, open-source editor with Python and Django support.

  • Cursor: An AI-powered code editor that integrates with GitHub Copilot and other AI tools.

  • PyCharm: A Python IDE with advanced Django support.

  • Vim/Neovim: Lightweight, keyboard-driven editors.

  • Emacs: Highly customizable editor.

Choose the editor or IDE that best fits your workflow. All you need is a text editor and a terminal to get started!

Creating a Virtual Environment

Once you have decided on a text editor or IDE, create a virtual environment with Python 3.12 using uv:

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate the virtual environment:
source .venv/bin/activate

Install development dependencies:

# Install all development dependencies
uv sync --dev

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 and local_test_settings.py files from the deploy subdirectory and then create your database:

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

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

Understanding the Settings Files

QATrack+ uses a layered approach to Django settings, with each file serving a specific purpose. Understanding this hierarchy will help you configure your development and testing environment.

Settings File Hierarchy (Highest to Lowest Precedence):

  1. `local_test_settings.py` - Your custom test environment overrides - Contains all essential development and test settings in one place - This is the main file you’ll customize for your testing needs

  2. `local_settings.py` - Your custom development environment overrides - Contains development-specific settings like database configuration

  3. `test_settings.py` - Default test environment settings - Contains test-specific defaults like password hashers and notification settings

  4. `settings.py` - Base Django application settings - Contains core Django configuration, installed apps, middleware, etc.

Collect Static Files

Before running the development server, you need to collect all static files to the STATIC_ROOT directory:

python manage.py collectstatic --noinput

Loading Default Data (Fixtures)

QATrack+ comes with pre-configured default data that provides a foundation for development and testing. This includes common QA categories, test frequencies, modalities, vendors, and other essential data structures.

To load the default data into your development database:

python manage.py loaddata fixtures/defaults/*/*

This command will populate your database all default data.

You can also load specific fixture categories individually if you only need certain data:

# Load only QA-related fixtures
python manage.py loaddata fixtures/defaults/qa/*

# Load only unit-related fixtures
python manage.py loaddata fixtures/defaults/units/*

# Load only service log fixtures
python manage.py loaddata fixtures/defaults/service_log/*

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:8000/ 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 available in multiple languages. For discussion of how to mark templates and strings for translation please read the Django docs on translation.

Adding a New Language to QATrack+

For detailed instructions on adding a new language to QATrack+, including step-by-step workflows and translation automation, please refer to the Add Language Tutorial in the tutorials section.

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

Using Make Commands

QATrack+ includes a Makefile with convenient shortcuts for common development tasks like running tests, formatting code, and building documentation. You can see all available commands by running:

make help

For detailed information about using make and understanding Makefiles, refer to the GNU Make Manual.

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.

Setting Up Selenium Browser Testing

QATrack+ includes Selenium tests that simulate user interactions with the web interface and are marked with the @pytest.mark.selenium decorator.

This setup should be completed before running the test suite if you want to see the Selenium tests in action.

Browser Requirements

You will need to have both a browser and its corresponding driver installed on your system:

  • Option 1. Firefox + geckodriver

  • Option 2. Chromium + chromedriver

If you are unsure whether or not you have both a browser and its corresponding driver installed, you can run the following commands to check:

Finding Browser and Driver Paths:

# Check for Firefox browser
which firefox

# Check for geckodriver
which geckodriver

# Check for Chromium browser
which chromium

# Check for chromedriver
which chromedriver

Example Output:

/usr/bin/firefox
/snap/bin/geckodriver
/snap/bin/chromium
/usr/bin/chromedriver

Installing Missing Components

If you do not have both firefox and geckodriver or both chromium and chromedriver, you can install either pair using the following commands:

# Option 1: Install Firefox and geckodriver
sudo apt install firefox geckodriver

# Option 2: Install Chromium and chromedriver
sudo apt install chromium-browser chromium-chromedriver

Manual Downloads (Alternative Installation)

If the package manager installation doesn’t work or you need a specific version, you can download the drivers manually:

After downloading, make the driver executable and verify the path.

Configuring Selenium Tests

You’ll need to configure your browser settings in two files. First, update the Selenium configuration in qatrack/settings.py:

# Selenium Browser Configuration
# Options: 'firefox', 'chromium'
SELENIUM_BROWSER = ''

# Browser Driver Paths
SELENIUM_FIREFOX_DRIVER_PATH = ''  # Path to geckodriver as shown above
SELENIUM_CHROMIUM_DRIVER_PATH = ''   # Path to chromedriver as shown above

# Headless Mode
# Set to True to run browsers in headless mode (no visible browser window)
# Set to False to see the browser during test execution
SELENIUM_VIRTUAL_DISPLAY = True

Then also update SELENIUM_VIRTUAL_DISPLAY in qatrack/test_settings.py:

# In qatrack/test_settings.py:
SELENIUM_VIRTUAL_DISPLAY = False  # Set to True to use headless browser for testing (requires xvfb)

Configuration Examples

Firefox with visible browser:

# In qatrack/settings.py:
SELENIUM_BROWSER = 'firefox'
SELENIUM_VIRTUAL_DISPLAY = False
SELENIUM_FIREFOX_DRIVER_PATH = '/snap/bin/geckodriver'

# In qatrack/test_settings.py:
SELENIUM_VIRTUAL_DISPLAY = False

Chromium with visible browser:

# In qatrack/settings.py:
SELENIUM_BROWSER = 'chromium'
SELENIUM_VIRTUAL_DISPLAY = False
SELENIUM_CHROMIUM_DRIVER_PATH = '/usr/bin/chromedriver'

# In qatrack/test_settings.py:
SELENIUM_VIRTUAL_DISPLAY = False

Headless mode

# In qatrack/settings.py:
SELENIUM_BROWSER = ''  # This can either be filled in or left blank
SELENIUM_VIRTUAL_DISPLAY = True

# In qatrack/test_settings.py:
SELENIUM_VIRTUAL_DISPLAY = True

Running The Test Suite

Once you have QATrack+ and its dependencies installed (and optionally configured Selenium browser testing above), 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/dev/projects/qatrackplus, inifile: pytest.ini
plugins: django-4.5.2, cov-3.0.0

qatrack/accounts/tests.py ✓✓✓

Running Different Types of Tests

Run all tests (including Selenium):

py.test

Run only Selenium tests:

pytest -m selenium

Run only non-Selenium tests (faster):

pytest -m "not selenium"

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

Customizing Organization Logos

QATrack+ reports include an option to display your organization’s logo.

Adding Your Organization Logo

  1. Prepare your logo file: - Use a PNG format for best compatibility - Recommended size: 200x60 pixels or similar aspect ratio - Keep file size reasonable (under 100KB)

  2. Replace the placeholder logo: - Navigate to qatrack/reports/static/reports/img/ - Replace the existing logo.png file with your own logo - Keep the same filename (logo.png) to avoid template changes

  3. Alternative: Use a different filename: - If you prefer a different filename, edit qatrack/reports/templates/reports/_header.html - Update all references from logo.png to your preferred filename - Update the alt text and fallback messages as needed

  4. Collect static files: After making changes, run:

    python manage.py collectstatic --noinput

Logo Display Options

  • HTML Reports: Logo is displayed using Django’s static file handling

  • PDF Reports: Logo uses file:// paths for compatibility with PDF generation

  • Error Handling: If the logo fails to load, nothing is displayed (no fallback message)

  • Visibility Control: Users can toggle logo display on/off in report settings

Customizing Logo Text

To change the alt text: - Edit qatrack/reports/templates/reports/_header.html - Update the translation strings for “Organization Logo” - Add translations to your locale files if using multiple languages

Note: The logo functionality is designed to be easily customizable without requiring code changes to the core application.

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 --port 8008

Version Naming Convention

QATrack+ uses Eff Ver (Effort Versioning) for its version naming convention. Eff Ver is a versioning strategy that focuses on the effort required to upgrade rather than semantic meaning. This approach prioritizes the practical impact on users and developers when considering version changes.

For more information about Eff Ver, see the Eff Ver documentation.

Version Number Structure

The version number follows the format X.Y.Z where:

  • X (Major): Corresponds to the Django LTS release version - Currently at 4.0.0 (Django 4.2 LTS) - When upgrading to Django 5.2 LTS, version will become 5.0.0 - This ensures compatibility and upgrade path alignment with Django

  • Y (Minor): Feature releases within the same Django LTS cycle

  • Z (Patch): Bug fixes and minor improvements

Examples: - 4.0.0: Initial release on Django 4.2 LTS - 4.1.0: Major feature release while staying on Django 4.2 LTS - 4.1.1: Bug fix release - 5.0.0: Upgrade to Django 5.2 LTS

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: QATrack+ supports multiple languages through its internationalization infrastructure. We welcome community contributions for translation files in different languages. Use the translation manager script to help automate translations, then refine them manually for accuracy. See the “Internationalization & Translation” section above for detailed commands.

  • 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!