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 — 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"]` — the JSON-schema literal needs it
`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.

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.

Keyboard shortcuts

Qleany Documentation