Files

François b9475c6e9b docs: refocus README on users, add quick_start + tutorial, fill CONTRIBUTING

- README.md: pruned developer-oriented sections (Sphinx setup, Qt
  Creator workflow, VSCode debugging, release procedure, AppImage
  Wayland note) and replaced them with a user-facing layout: pre-built
  releases pointer, quick start, manual install, troubleshooting,
  licence.
- CONTRIBUTING.md: absorbed the developer content (debugging in VSCode,
  Qt GUI regen, Sphinx build, validation suite — batch + GUI variants,
  cross-distrib check, release procedure).
- doc/quick_start.md: 5-minute path from install to a passing test,
  in batch mode and in the GUI.
- doc/tutorial.md: guided walk-through against a small calc.py
  module — check, py_func, expected_result, $(...) expansion, group,
  let, condition, report (with the mkdir reminder), context_id.
- CLAUDE.md: subprocess API contract, bins.py, report-exporter
  plugin section, packaging matrix (wheel / PyInstaller / Flatpak /
  .deb work-in-progress), refreshed recent-fixes list. README/CLAUDE
  validation command no longer carries the spurious "-l" flag (which
  is GUI-only and a no-op in batch).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

2026-05-05 09:18:59 +02:00

4.7 KiB

Raw Blame History

Contributing to testium

Thank you for your interest in contributing to testium.

License of contributions

testium is licensed under the European Union Public Licence v. 1.2 (EUPL-1.2) — see the LICENSE file at the repository root.

By submitting a contribution to this project (pull request, patch, issue attachment, or any other form of code, documentation or media), you agree that your contribution is licensed to the project and to the public under the same EUPL-1.2 terms (or any later version of the EUPL approved by the European Commission), and you certify that:

you are the author of the contribution, or you have the right to submit it under the EUPL-1.2;
to the best of your knowledge, the contribution does not infringe any third-party intellectual-property rights;
the contribution may be redistributed by the project under the EUPL-1.2 and any compatible licence listed in the EUPL-1.2 Appendix.

This is the inbound = outbound rule: contributions come in under the same licence the project ships under.

You retain copyright on your contribution. The project does not ask you to sign a CLA or assign your copyright.

SPDX header in new source files

When creating a new source file, please include the following header at the top of the file (adjust the comment marker to the file's language):

# SPDX-License-Identifier: EUPL-1.2
# Copyright (c) <year> <your name>

For existing files, keep the header that is already there.

How to contribute

Open an issue describing the change you want to make (bug, feature, doc).
Fork the repository, create a topic branch.
Commit with a clear message (one logical change per commit).
Make sure the validation suite still passes:
```
./run.sh -b -- test/validation/main.tum
```
Open a pull request against main.

Coding conventions

Python ≥ 3.11
Follow existing style in the file you are modifying
Add or update tests in test/validation/ for new test items or behaviours
Update CLAUDE.md and the Sphinx manual for user-visible changes

Development

Debugging in VSCode

The recommended workflow:

Add a debug configuration to .vscode/launch.json:

{
    "configurations": [
        {
            "name": "Python : testium",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/src/testium",
            "console": "integratedTerminal",
            "args": ["-g"],
            "justMyCode": true
        }
    ]
}

Install debugpy in the venv: python -m pip install debugpy.
Open the Run and Debug tab and press play. testium starts; load and run a .tum file. Set breakpoints where you want to investigate.

Qt GUI modification

UI files (*.ui) are edited in Qt Creator. After editing, regenerate the corresponding Python and resource files:

scripts/qt_generate.sh

Icons come from https://github.com/free-icons/free-icons.

Sphinx documentation

pip install sphinx linuxdoc
doc/manual/sphinx/build_doc.sh

PDF generation requires texlive:

sudo apt install texlive-full

Validation suite

Batch mode (CI-friendly, headless):

./run.sh -b -- test/validation/main.tum

GUI mode (loads the suite, click Run to execute and inspect the tree):

./run.sh test/validation/main.tum

GUI run-and-close (executes the suite, then closes):

./run.sh -r -- test/validation/main.tum

Subset run via the items define (works in any mode):

./run.sh -b -d "items=['parallel','common']" -- test/validation/main.tum

Cross-distribution check

package/deb/test_distro.sh spins up a Docker/Podman container of the target image, installs the expected system Python deps via apt (with pip fallback for what is missing), installs the testium wheel and runs the validation suite end-to-end. Currently green on debian:bookworm, debian:trixie, ubuntu:24.04.

./package/deb/test_distro.sh debian:trixie

Release procedure

Update release_note.txt.
Bump the version in src/VERSION.
Make sure the documentation is up to date — rebuild with doc/manual/sphinx/build_doc.sh if needed.
Push and tag the commit with the new version.
Build the binary release: package/pyinstaller/build.sh.
Run the validation suite against each generated binary.
Confirm all validation results are green before publishing.

Reporting security issues

Please do not report security vulnerabilities through public GitHub issues. Instead, send an email to the project maintainer directly.

Questions

Open a GitHub Discussion or an issue tagged question.

4.7 KiB Raw Blame History