Thanks for being here. RustConn is a GTK4/libadwaita connection manager written in Rust, and it grows from bug reports, translations, packaging fixes, and code alike. This file explains how to get a change merged.
By participating you agree to follow the GNOME Code of Conduct; CODE_OF_CONDUCT.md says where it applies and how to report a problem.
| Where to start | |
|---|---|
| Report a bug | New issue — the bug form asks for the version, install method, and desktop, all of which matter |
| Request a feature | New issue — describe the workflow you are trying to complete, not only the widget you want |
| Translate | .po files in po/ — see Translations below |
| Fix or build something | Read Development setup, then The quality gate |
| Package for a distro | packaging/ holds the Flatpak, OBS, Snap, nixpkgs, and macOS manifests |
| Improve the docs | docs/ — the user guide and CLI reference are the two most read |
| Report a vulnerability | Not in an issue. Use Security Advisories; see SECURITY.md |
For anything larger than a bug fix, open an issue first. It is cheaper to agree on the approach in a paragraph than to rewrite a finished branch.
Prerequisites, per-distro system packages, and every feature flag are in the Build Guide. The short version on a Debian-family system:
sudo apt install build-essential libgtk-4-dev libvte-2.91-gtk4-dev \
libadwaita-1-dev libdbus-1-dev libssl-dev pkg-config libasound2-dev \
clang cmake gettext
git clone https://github.com/totoshko88/RustConn.git
cd RustConn
cargo build
cargo run --bin rustconnThe toolchain is pinned in rust-toolchain.toml, so rustup picks the right
compiler on its own. MSRV is a separate, older number (rust-version in
Cargo.toml, currently 1.95) and CI checks it in its own job — avoid syntax and
APIs newer than that.
docs/ARCHITECTURE.md is worth a skim before your first patch; it explains why the code is split the way it is.
CI runs a job per gate and a red one blocks the merge. You can reproduce all of the important ones locally:
cargo fmt --all # formatting (CI runs --check)
cargo clippy --all-targets # must be 0 warnings
cargo test --workspace # ~2.5 min including the compile
typos # spell check, configured in typos.toml
cargo machete # unused dependenciesLocal tools beyond cargo itself. scripts/verify.sh skips a gate whose tool is
missing and lists every skipped tool in its summary, so "all gates passed" with
a skip line above it means not checked:
| Tool | Install | Used by |
|---|---|---|
typos |
cargo install typos-cli |
verify.sh, CI hygiene |
cargo-machete |
cargo install cargo-machete |
verify.sh, CI hygiene |
cargo-nextest |
cargo install cargo-nextest |
CI test (locally cargo test is enough) |
cargo-deny |
cargo install cargo-deny |
CI cargo-deny (licences, advisories, bans) |
cargo-audit |
cargo install cargo-audit |
scripts/dep-audit.sh; also lists unmaintained crates |
rpmspec, rpmlint |
your distro's rpm and rpmlint packages |
CI rpm-spec |
Xvfb (xvfb-run) |
your distro's xorg-x11-server-Xvfb / xvfb |
scripts/run-ignored-gui-tests.sh, scripts/gui-smoke.sh |
Install system packages with your package manager; the cargo tools build from
source into ~/.cargo/bin.
The #[ignore]d GTK tests and the launch smoke test need a display and are not
part of cargo test. CI runs them under Xvfb; locally:
xvfb-run -a scripts/run-ignored-gui-tests.sh # one process per test
cargo build -p rustconn && xvfb-run -a scripts/gui-smoke.shA debug build is large: a full workspace target/ reaches about 23 GB with
tests and clippy artefacts. Point CARGO_TARGET_DIR at a disk with room (for
example one per worktree) and cargo clean it when you are done.
Two traps worth knowing before they cost you an hour:
- Never
cargo clippy --all-features. It turns on a gtk3-dependent path that fails at build time on a missinggdk-3.0.pc. Use--all-targets. - A repeat clippy run with nothing changed reports nothing. It prints
Finished ... in 0.2sand zero warnings without inspecting anything. Touch the files you changed, orcargo clean -p <crate>, if you need a real answer.
Beyond that, CI also runs the i18n gates (scripts/check-potfiles.sh,
check-i18n-escapes.sh, check-pot-current.sh, check-po-complete.sh),
cargo-deny for licences and advisories, and a macOS job for the -sys crates.
./scripts/verify.sh runs the whole battery in one go if you would rather not
remember the list — --quick for docs- or translation-only work, --tests to
include cargo test --workspace. It writes everything to target/verify.log.
These are structural, not stylistic, and they are the ones most often missed.
Crate boundaries. There are eight crates and only rustconn may import
gtk4, adw, or vte4. rustconn-core is the domain logic and
rustconn-cli sits on top of it; neither may touch a GUI crate. Business logic
belongs in core even when the bug was reported against a dialog.
unsafe lives in exactly five crates. rustconn-pty-sys,
rustconn-locale-sys, rustconn-env-sys, rustconn-dock-sys, and
rustconn-lock-sys are the isolated FFI helpers, and the workspace denies
unsafe_code everywhere else. New FFI gets a new -sys crate rather than an
exception where the caller lives.
Credentials. Passwords, keys, and tokens are secrecy::SecretString, never
String. An intermediate expose_secret().to_string() gets wrapped in
zeroize::Zeroizing::new(). Secrets reach external CLIs over a stdin pipe,
never as Command::arg(password), and never appear in a log line or an error
message.
Errors and logging. Errors are thiserror::Error types; no unwrap() or
expect() in production code (both are fine in tests). Logging goes through
tracing — no println! or eprintln!, except in rustconn-cli, where
printing is the interface.
Every user-facing string is translatable. Wrap it in i18n() or i18n_f()
with {} placeholders, then regenerate the template with
bash po/update-pot.sh. A source file containing i18n() must also be listed in
po/POTFILES.in or its strings are silently dropped.
No std::env::set_var / remove_var. They are unsafe in Rust 2024. The
single exception is rustconn-env-sys::set_startup_var, whose window is already
closed by its two existing callers.
Accessibility. New widgets need accessible labels, and dialogs follow the
GNOME HIG. adw::AlertDialog rather than
gtk::MessageDialog.
The full set, with the reasoning behind each rule, lives in
.kiro/steering/ — core-rules.md is the entry point. Each
crate also has its own AGENTS.md with contracts specific to that tree.
Minimum viable change. Before adding code, stop at the first of these that
holds: does it need to exist; does this repo already have it; does std cover
it; is there a GTK4/libadwaita feature for it; does an existing dependency do
it. Prefer deleting over adding and boring over clever. No new dependency,
abstraction, or generic that the change did not require.
Fix root causes. If a report names one call site, check the other callers of the function you are touching and fix the shared function once.
A deliberate simplification gets a // ponytail: comment naming the ceiling and
the upgrade path, for example:
// ponytail: O(n²) scan, fine for <100 hosts; index if the list growsNon-trivial logic leaves behind one runnable check — a property test in
rustconn-core/tests/properties/ or an integration test in
rustconn-core/tests/integration/, both registered in the directory's mod.rs.
For a -sys crate it is the contract test that asserts the precondition guard,
since the FFI call itself is not reachable from a test harness.
Conventional commits, imperative mood, lowercase, no trailing period:
fix(rustconn-core): resolve jump host before launching SFTP
Types: feat, fix, docs, style, refactor, test, chore, perf,
ci, build. Scopes: rustconn-core, rustconn-cli, rustconn (GUI),
i18n, packaging, ci. Use the commit body for why, not what — the diff
already covers what.
Keep unrelated changes in separate commits.
Any user-facing change gets a CHANGELOG.md entry under ## [Unreleased],
following Keep a Changelog. Sections in
this order, empty ones omitted: Added, Fixed, Changed, Removed,
Improved, Documentation, Dependencies. Each entry opens with a bold
summary and an optional issue reference, then explains itself in the same
bullet:
### Fixed
- **Jump host ignored by SFTP launches (issue #123)** — the SFTP path read the
picker's field directly instead of the three-tier resolver, so a bastion
inherited from a group was dropped.RustConn ships every catalogue listed in po/LINGUAS. ls po/*.po is the
authoritative list — numbers written in prose have been wrong before.
Every language is welcome, with one exception: the project does not ship a
Russian translation, and a Russian catalogue will not be merged. This is a
decision about the product, explained in the
maintainer's reply on PR #413.
It is not a rule about people: anyone may contribute in any other language. New
languages of the region, such as Bashkir (ba), Tatar (tt) and Nogai
(nog), are as welcome as every other language, and Kazakh (kk), which
RustConn already ships, always needs maintainers.
To correct or complete an existing language, edit its po/<lang>.po and run the
three gates:
./scripts/check-potfiles.sh # POTFILES.in matches reality
./scripts/check-i18n-escapes.sh # no \u{...} in translatable literals
./scripts/check-po-complete.sh # no fuzzy or missing entriesFuzzy entries matter as much as missing ones: gettext ignores a fuzzy string and falls back to English, so it looks translated in the statistics and untranslated on screen.
For a new language, copy po/rustconn.pot to po/<lang>.po, add the code to
po/LINGUAS, and translate. Placeholders are {}, positional, in source order —
a translation may not reorder or drop one. Write characters directly rather than
as \u{...} escapes; the escape survives extraction and reaches the user
verbatim.
More detail in po/AGENTS.md.
- Branch off
main. - Make the change, with a test if the logic is non-trivial.
- Run the quality gate above.
- Update
CHANGELOG.mdif the change is user-facing. - Open the PR. The template asks you to confirm the same list.
Do not silence a lint, drop a test, or skip i18n() to make a branch look
finished. If something external is genuinely blocking you — an upstream bug, a
new compiler lint — say so in the PR and it will get sorted out together.
Small, reviewable PRs land faster than large ones. If a change spans crate boundaries, name the boundary in the description and keep each layer readable on its own.
The maintainer develops RustConn with AI coding agents: Kiro, with Claude
models. The agents' configuration is public, in .kiro/ (steering
files, hooks and agent profiles) and in the AGENTS.md files at the root and in
each crate, so you can read exactly what they are told.
What holds for every change, whoever or whatever wrote it:
- The maintainer reads it before it goes into the repository.
- It passes
scripts/verify.sh --tests: formatting, clippy with-D warnings, rustdoc with-D warnings, the test suite, and the i18n and crate-boundary gates. It is then tested by hand. - Flathub manifests and Flathub submissions are written by hand, as Flathub's policy requires.
Since 12 November 2026, a commit made with an agent carries a Co-Authored-By
trailer naming it. Most earlier agent-assisted commits, including most of the
0.24.11 cycle, do not have one.
You may use AI tools for your own contributions. You must understand what you submit and be able to explain it in review: why the change is needed, what it does, and how you checked it.
Releases are cut by the maintainer. ./scripts/release.sh runs every gate and
then tags, pushes, and triggers the artifact build plus the Flathub, OBS, and
Snap updates, so please do not run it, pass --yes, or push a v* tag on a
contribution. A --dry-run is welcome if you want to check that your change
does not break the release gates.
RustConn is GPL-3.0-or-later. By submitting a contribution you agree that it is licensed under the same terms. There is no CLA.
- User Guide and CLI Reference
- Discussions for questions
- Issues for bugs and feature requests