| 1 | ---
|
| 2 | description: posprint development conventions
|
| 3 | globs: **/*
|
| 4 | alwaysApply: true
|
| 5 | ---
|
| 6 |
|
| 7 | # posprint development rules
|
| 8 |
|
| 9 | ## Language and dependencies
|
| 10 |
|
| 11 | - Single language: **Rust** with **egui** (eframe) for the UI.
|
| 12 | - Prefer std library and in-house code. Add a crate only when reimplementing would be unreasonable (e.g. `serialport`, `serde`, `image`, UI framework).
|
| 13 | - ESC/POS encoding lives in `src/escpos.rs` — do not add the `escpos` crates.io package.
|
| 14 | - Printing: **USB-serial only** in v0.1.x. No Bluetooth or USB printer-class until explicitly requested.
|
| 15 |
|
| 16 | ## Testing
|
| 17 |
|
| 18 | - **Every module must have unit tests** in `#[cfg(test)] mod tests` (or `tests/` for integration).
|
| 19 | - New behaviour requires new tests in the same commit.
|
| 20 | - Run `cargo test` before merging; all tests must pass.
|
| 21 | - Use `MockTransport` for printer I/O in tests; never require hardware in CI.
|
| 22 |
|
| 23 | ## Branches and commits
|
| 24 |
|
| 25 | - Default branch: `master`.
|
| 26 | - Use `feature/` or `fix/` branches for changes.
|
| 27 | - Commit frequently with focused messages; avoid one large commit at the end.
|
| 28 | - Merge to `master` only after `cargo test` is green.
|
| 29 |
|
| 30 | ## Git merges
|
| 31 |
|
| 32 | - **Never fast-forward.** Always create a merge commit:
|
| 33 | ```bash
|
| 34 | git checkout master
|
| 35 | git merge --no-ff feature/your-branch
|
| 36 | ```
|
| 37 | - Do not use `git pull --ff-only` when integrating a merged feature branch into `master`.
|
| 38 |
|
| 39 | ## Branch cleanup
|
| 40 |
|
| 41 | - After a successful merge to `master`, delete the local branch:
|
| 42 | ```bash
|
| 43 | git branch -d feature/your-branch
|
| 44 | ```
|
| 45 | - If a feature branch was pushed to the remote, delete it there too once merged:
|
| 46 | ```bash
|
| 47 | git push origin --delete feature/your-branch
|
| 48 | ```
|
| 49 | - Periodically prune stale remote-tracking refs: `git fetch --prune`
|
| 50 |
|
| 51 | ## Documentation
|
| 52 |
|
| 53 | - See `.cursor/rules/documentation.mdc` for full doc-sync rules.
|
| 54 | - Keep `docs/HELP.md` in sync with supported DSL and UI features.
|
| 55 | - The in-app Help tab must mirror `docs/HELP.md` (via `include_str!` in `src/lib.rs`).
|
| 56 | - Update `docs/ARCHITECTURE.md`, `docs/PRINTING.md`, etc. when implementation diverges from design.
|
| 57 |
|
| 58 | ## Releases
|
| 59 |
|
| 60 | - GitLab CI (`.gitlab-ci.yml`) runs tests on push.
|
| 61 | - Tagged releases produce Windows `.exe`, Debian `.deb` (apt), and Arch `.pkg.tar.zst` (pacman).
|
| 62 | - Debian packages use `cargo-deb` and `[package.metadata.deb]` in `Cargo.toml`.
|
| 63 | - Arch packages use `packaging/arch/PKGBUILD` and `makepkg`.
|