Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Contributing to Qleany

Thank you for your interest in contributing to Qleany! This document provides guidelines and information for contributors.

Code of Conduct

Please be respectful and constructive in all interactions. We aim to maintain a welcoming environment for everyone.

How to Contribute

Reporting Issues

  • Check existing issues before creating a new one
  • Provide a clear description of the problem
  • Include steps to reproduce, expected behavior, and actual behavior
  • Mention your environment (OS, Rust version, etc.)

Suggesting Features

  • Open an issue describing the feature and its use case
  • Explain why this would be valuable for Qleany users
  • Be open to discussion about alternative approaches

Submitting Code

  1. Fork the repository
  2. Create a feature branch from main
  3. Make your changes
  4. Ensure your code follows the project’s style
  5. Test your changes
  6. Submit a pull request

Regenerating Qleany’s own backend

Qleany generates itself from the qleany.yaml at the repo root, so a template change can be applied to this repo too. That is worth doing, and it is how the generator dogfoods its own output, but a blanket qleany generate destroys this repository, and the reasons are not obvious.

Never run a bare qleany generate here

Right now 90 of this repo’s 233 generated files report as [M] modified or [N] new; run qleany list files --all for the current split. The Generated by Qleany header is stripped from both sides before the comparison, so a file is flagged by real content drift, never by a version bump. generate defaults to modified + new, so a bare run rewrites all 90, including every one of the 47 Scaffold files, which hold every hand-written use-case body in the project. Use generate file <path>, a nature filter, or the read-only generate --all --temp.

What must never be regenerated

PathWhy
crates/*/src/use_cases/*_uc.rs, */units_of_work/*_uow.rsScaffold. These are Qleany’s implementation; the generated form is unimplemented!().
Cargo.toml (root)Marked Aggregate, but hand-maintained. The qleany-* package names do survive, but the generated form resets the version to 0.0.1 and the licence to MIT OR Apache-2.0, blanks homepage and repository, and replaces the real authors, description, keywords and categories with placeholders. Worse, the member list is rebuilt from qleany.yaml: crates/naming and the naming workspace dependency vanish (that crate is not in the manifest, yet three crates depend on it), the serde_json workspace dependency goes with them, and crates/frontend and crates/cli are added although neither directory exists. The regenerated workspace does not build.
crates/*/Cargo.tomlSame: the generated form carries only the skeleton dependencies, dropping tera, rayon, similar, heck, include_dir and the rest.

What must be re-applied after regenerating

These live inside generated files, so regeneration drops them. After a regen, check each one is still present:

FileHand-written addition
crates/common/src/lib.rspub mod enum_variant_parser; · pub mod generator;
crates/handling_manifest/src/lib.rs#![recursion_limit = "256"], which the JSON-schema literal needs
crates/{handling_manifest,rust_file_generation,cpp_qt_file_generation,file_generation_shared_steps}/src/use_cases.rsmod common;, each feature’s shared helpers
crates/handling_manifest/src/dtos.rsCheckRuleDto
crates/handling_manifest/src/handling_manifest_controller.rsget_check_rules() and its use crate::CheckRuleDto;
crates/{rust,cpp_qt}_file_generation/src/*_controller.rslet uc = Generate{Rust,CppQt}CodeUseCase::new(…) without mut: those two use cases are hand-tightened to execute(&self), which the template cannot know

The procedure

git commit                                   # non-negotiable; regen overwrites
cargo build --workspace                      # build the generator you will run

qleany generate --all --temp                 # read-only: writes only ./temp/
diff -r temp/crates crates | less            # review before writing anything

qleany generate -M -i                        # modified Infrastructure
qleany generate -M -g                        # modified Aggregate
git checkout -- Cargo.toml crates/*/Cargo.toml   # undo the manifest clobber
# …re-apply the table above…
cargo fmt --all
cargo check --workspace && cargo test --workspace && ./run_tests.sh

Finally, confirm it is a fixed point: regenerate a second time and expect no diff. If the second pass changes anything, a template is not stable and that is a bug worth fixing before landing.

Working against an unreleased teksilo

crates/teksilo_ui depends on teksilo from crates.io. The version is declared once, in the workspace Cargo.toml.

To build against a local teksilo checkout instead, add an untracked .cargo/config.toml at the repository root:

[patch.crates-io]
teksilo = { path = "../teksilo/crates/teksilo" }

.cargo/ is gitignored. The patch applies only when the local crate’s version satisfies the requirement in Cargo.toml, so both move together.

A patch rewrites Cargo.lock on every cargo invocation, replacing the registry entries for teksilo and everything below it with local paths. A lockfile in that state does not resolve on any other machine. Restore it before committing:

git checkout -- Cargo.lock tests/rust/Cargo.lock

tools/check_lockfile_is_portable.py checks this, and runs from run_tests.sh and CI.

Two tools are installed separately and should match the teksilo version in use:

cargo install cargo-teksilo-fmt --locked
cargo install teksilo-automation-mcp --locked

The first formats teksu! macro bodies, which cargo fmt leaves alone. The second is what scripts/automation_*.py attach to.

UI automation

Use a Python virtual environment and install the probe dependencies:

python3 -m venv /tmp/qleany-probes
. /tmp/qleany-probes/bin/activate
python3 -m pip install -r scripts/requirements-automation.txt
python3 -m unittest discover -s scripts/tests -v
python3 scripts/automation_guards.py

The live probes use the Teksilo-provided scripts/teksilo_probe harness. Refresh that generated directory with cargo teksilo init; do not edit it by hand. TEKSILO_MCP_BIN selects a version-matched teksilo-automation-mcp executable. A working desktop display is required (CI uses Xvfb and Openbox). Run probes sequentially. Each probe builds the application, uses an isolated configuration and temporary manifest, and returns 0 for success, 1 for execution errors, or 2 for failed behavior assertions. CI runs every automation_*.py except the shared automation_fixture.py.

Coverage beyond screen smoke tests includes:

ProbeInteractions and assertions
automation_guards.pySave before New/Open/Close; failed-save preservation and recovery; title-bar Quit Save/Discard/Cancel
automation_collections.pyPointer drag on entities, fields, features, use cases and DTO fields; undo/redo and exact saved order; row overflow deletion, cascade cancellation, DTO disable and subtree restoration
automation_check.pyW06 ownership warning, resolution through a field edit, critical errors and generation gating
automation_options.pyInheritance, entity flags, relationship variants and flags, use-case flags and associations, DTO field flags; exact YAML persistence
automation_save.pyUnsubmitted text enables Save and persists into the exact YAML field across the editors
automation_generate.pyStatus/nature filters, individual and bulk selection, temporary/project destinations, recompute cancellation
automation_user_interface.pyEvery Rust and C++ UI target toggle persists into its exact YAML flag
automation_shell.py, automation_wizard.pyTheme switching and wizard Back retaining values, in addition to existing shell/wizard checks

This is interaction coverage, not exhaustive UI coverage. Native Open, Save As and creation-folder pickers require OS-dialog automation outside the in-process Teksilo harness. External browser/folder launches, visual layout across window sizes, complete keyboard traversal, and generation error/retry paths still need separate coverage. Developer manifest-open shortcuts do not cover native pickers.

Developer Certificate of Origin

This project uses the Developer Certificate of Origin (DCO).

By contributing to this repository, you agree to the DCO. You must sign off your commits to indicate your agreement:

git commit -s -m "Your commit message"

This adds a Signed-off-by: Your Name <your.email@example.com> line to your commit, certifying that you wrote or have the right to submit the code under the project’s license (MPL-2.0).

Setting up automatic sign-off

You can configure Git to always set your identity for your commits for this repository:

git config user.name "Your Name"
git config user.email "your.email@example.com"

Then use git commit -s for each commit, or create a Git alias:

git config --global alias.cs "commit -s"

What if I forgot to sign off?

You can amend your last commit:

git commit --amend -s

For multiple commits, you may need to rebase:

git rebase --signoff HEAD~N

(Replace N with the number of commits to sign off)

License

By contributing to Qleany, you agree that your contributions will be licensed under the Mozilla Public License 2.0.

Questions?

If you have questions about contributing, feel free to open an issue for discussion.