Skip to content

Latest commit

 

History

History
300 lines (228 loc) · 13.6 KB

CONTRIBUTING.md

File metadata and controls

300 lines (228 loc) · 13.6 KB

Contributing to RustConn

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.

Ways to contribute

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.

Development setup

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 rustconn

The 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.

The quality gate

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 dependencies

Local 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.sh

A 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 missing gdk-3.0.pc. Use --all-targets.
  • A repeat clippy run with nothing changed reports nothing. It prints Finished ... in 0.2s and zero warnings without inspecting anything. Touch the files you changed, or cargo 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.

Rules that will get a PR sent back

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.

Style

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 grows

Non-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.

Commits

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.

Changelog

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.

Translations

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 entries

Fuzzy 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.

Pull requests

  1. Branch off main.
  2. Make the change, with a test if the logic is non-trivial.
  3. Run the quality gate above.
  4. Update CHANGELOG.md if the change is user-facing.
  5. 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.

AI-assisted development

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

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.

Licence

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.

Getting help