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
- Fork the repository
- Create a feature branch from
main - Make your changes
- Ensure your code follows the project’s style
- Test your changes
- 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
| Path | Why |
|---|---|
crates/*/src/use_cases/*_uc.rs, */units_of_work/*_uow.rs | Scaffold. 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.toml | Same: 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:
| File | Hand-written addition |
|---|---|
crates/common/src/lib.rs | pub 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.rs | mod common;, each feature’s shared helpers |
crates/handling_manifest/src/dtos.rs | CheckRuleDto |
crates/handling_manifest/src/handling_manifest_controller.rs | get_check_rules() and its use crate::CheckRuleDto; |
crates/{rust,cpp_qt}_file_generation/src/*_controller.rs | let 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:
| Probe | Interactions and assertions |
|---|---|
automation_guards.py | Save before New/Open/Close; failed-save preservation and recovery; title-bar Quit Save/Discard/Cancel |
automation_collections.py | Pointer 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.py | W06 ownership warning, resolution through a field edit, critical errors and generation gating |
automation_options.py | Inheritance, entity flags, relationship variants and flags, use-case flags and associations, DTO field flags; exact YAML persistence |
automation_save.py | Unsubmitted text enables Save and persists into the exact YAML field across the editors |
automation_generate.py | Status/nature filters, individual and bulk selection, temporary/project destinations, recompute cancellation |
automation_user_interface.py | Every Rust and C++ UI target toggle persists into its exact YAML flag |
automation_shell.py, automation_wizard.py | Theme 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.