Your Android phone and your Windows PC, working as one. Local-first, end-to-end encrypted, no account.
Contributing
This guide summarizes the repository conventions, module header requirements, protocol change rules, and pre-submission checks for contributing to NectarLink. See also the root CONTRIBUTING.md and LICENSE.
License
NectarLink uses three licenses across the repository (see LICENSE):
- Core libraries (
core/nectarlink-protocol,core/nectarlink-core,core/nectarlink-ffi):MPL-2.0 - Applications and CLI (
desktop/app,desktop/vcam,android,cli):GPL-3.0-or-laterwith anapp-store exception - Protocol specification and documentation (
docs/):CC BY 4.0
Contributions are accepted under the Developer Certificate of Origin.
SPDX Header Policy
Every Rust (.rs), Kotlin (.kt), C++ (.cpp, .h), and QML (.qml) source file must start with the appropriate SPDX-License-Identifier comment:
// SPDX-License-Identifier: MPL-2.0
or for application and CLI files:
// SPDX-License-Identifier: GPL-3.0-or-later
- Verified automatically by
scripts/check-headers.ps1andscripts/check.ps1. - Never log message text, phone numbers, contact names, file paths, or clipboard contents (see
docs/protocol/v0.mdsection 11).
Code Style and Static Analysis
Rust
- Formatting: Format all Rust code with
cargo fmt --all. Configuration lives inrustfmt.toml. - Lints: Workspace-wide lints are configured in the root
Cargo.toml(unsafe_op_in_unsafe_fn = "warn",dbg_macro = "warn",todo = "warn"). All code must passcargo clippy --workspace --all-targets -- -D warningswith zero warnings. - Error Handling:
- Use typed
thiserrorenums (CoreError,FrameError,PairError) acrossnectarlink-protocolandnectarlink-corepublic APIs. - Never unwrap fallible network, CBOR, file I/O, or SQLite operations on untrusted peer inputs.
- Use typed
unsafeBlocks:- Avoid
unsafeinnectarlink-protocolandnectarlink-core. - Where Win32/COM/FFI calls require
unsafe(such asDpapiKeyProtector,desktop/vcamCOM interfaces, ordesktop/appWin32/WASAPI/DXGI interop), keep theunsafeblock minimal and document the pointer/lifetime invariants.
- Avoid
Kotlin (Android)
- Follow standard Kotlin conventions (
kotlin.code.style=officialinandroid/gradle.properties). - Run blocking disk, SQLite, or FFI calls on
Dispatchers.IO, never on the main UI thread. - Keep
Composelist items free of per-frame allocations (such asSimpleDateFormatcreation insideLazyColumnitem blocks) to preserve the< 5%scroll jank budget.
QML (Windows Desktop)
- Read colors, spacing, radii, and typography exclusively from the
Themesingleton (desktop/app/src/bridge/theme_tokens.rs) rather than hardcoding hex literals. - Gate continuous animations (
NumberAnimation,RotationAnimator) on item visibility and active window state so minimized tray mode consumes0.00%CPU.
Adding or Modifying a Capability
When introducing a new cross-device capability or extending an existing wire message:
- Specification First (
docs/protocol/): Document the capability ID, stream framing, CBOR message schemas, and error handling indocs/protocol/and register the capability indocs/protocol/capabilities.md. - Protocol Constants & Types (
core/nectarlink-protocol):- Add the capability constant in
src/capabilities.rs(and include it inALLif advertised by default). - Define the serde-serializable structs in
src/messages.rsusing#[serde(default)]/#[serde(skip_serializing_if = "Option::is_none")]so wire changes remain backward-compatible.
- Add the capability constant in
- Authorization Mapping (
core/nectarlink-core/src/features.rs):- Map the capability in
feature_for_capabilityto an existing or new toggle inDEVICE_TOGGLES. - Decide whether the feature is default-on or high-sensitivity opt-in (
default_enabled: false), and whether it must be restricted overConnectionPath::Relay(Connect over mobile data /away_mode).
- Map the capability in
- Core & FFI Plumbing (
core/nectarlink-core,core/nectarlink-ffi):- Implement the handler in
nectarlink-coreand enforceself.capabilities.is_allowed(&peer, cap::...)on both inbound and outbound paths. - If Android needs the API, expose it in
core/nectarlink-ffi/src/lib.rsand runandroid\gradlew.bat generateUniffiBindings(orcargo run -p nectarlink-ffi --bin uniffi-bindgen).
- Implement the handler in
- Two-Device Integration Test (
core/nectarlink-core/tests/two_devices.rs):- Add an end-to-end test spinning up two in-process
Nodeinstances over QUIC to verify capability negotiation, happy-path execution, and toggle denial behavior.
- Add an end-to-end test spinning up two in-process
Database Migrations (core/nectarlink-core/src/store.rs)
If a change alters the SQLite schema:
- Increment
SCHEMA_VERSIONincore/nectarlink-core/src/store.rs. - Add an idempotent migration step in
Store::migrate(usingALTER TABLEorCREATE TABLE IF NOT EXISTS) so existing user databases upgrade without data loss. - Add a unit test in
store.rsverifying both fresh database creation and migration from the previous version.
Pre-Submission Checklist
Before opening a pull request or merging a change, run the full verification script from the repository root:
powershell -ExecutionPolicy Bypass -File scripts\check.ps1
Verify that:
cargo fmt --all -- --checkproduces no diff.cargo clippy --workspace --all-targets -- -D warningsexits cleanly.cargo test --workspacepasses all unit and integration tests.scripts/check-headers.ps1reportsOK.cargo xtask tokens --checkconfirms generated design token files are in sync.android/gradlew.bat compileDebugKotlinsucceeds when Android or FFI code is touched.