Skip to content

contributing.md

Latest commit

 

History

History
249 lines (190 loc) · 7 KB

contributing.md

File metadata and controls

249 lines (190 loc) · 7 KB
Raw

Mitwirken

Aus dem Quellcode bauen

xfetch ist in Rust (Edition 2024) geschrieben. Um aus dem Quellcode zu bauen, benotigen Sie Rust (installieren Sie es uber rustup auf rust-lang.org).

Voraussetzungen

  • Rust-Toolchain (Edition 2024)
  • Cargo (im Rust-Umfang enthalten)

Klonen und Bauen

git clone https://github.com/xfetch-cli/xfetch.git
cd xfetch
cargo build --release

Das Binary wird unter target/release/xfetch abgelegt.

Aus dem Quellcode installieren

cargo install --path .

Dies installiert das Binary nach ~/.cargo/bin/xfetch.

Projektstruktur

Das xfetch-Okosystem ist als Multi-Repository-Architektur unter der GitHub-Organisation xfetch-cli organisiert:

xfetch/
  api/              # Plugin API SDK (Rust Crate)
  assets/           # Logo- und Banner-Assets
  configs/          # Offentliche Preset-Konfigurationen
  plugins/          # Offizielle Plugin-Implementierungen (Workspace)
  web/              # Landingpage (Next.js)
  xfetch/           # Haupt-CLI-Anwendung (Rust)

Haupt-CLI (xfetch/)

xfetch/
  src/
    main.rs           # Einstiegspunkt
    cli.rs            # CLI-Argument-Parsing (clap)
    config.rs         # JSONC-Konfigurationsladen
    cache.rs          # Daten-Caching mit TTL
    ui.rs             # Render-Orchestrator
    ui/
      nodes.rs        # Render-Baum-Vorbereitung
      layout.rs       # Layout-Verteilung
      logo.rs         # Logo-Laden (ASCII, Bild)
      print.rs        # Terminal-Ausgabe-Rendering
      renders.rs      # Layout-Render-Implementierungen
      x.rs            # Pfaderweiterungs-Hilfsfunktionen
    info/
      mod.rs          # Info-Struktur und Orchestrierung
      system.rs       # OS-, Kernel-, Netzwerkinfo
      software.rs     # Shell-, Terminal-, Paket-, Benutzerinfo
      hardware.rs     # CPU-, GPU-, Speicher-, Festplatten-, Akkuinfo
    plugins/
      mod.rs          # Plugin-Erkennung und -Benennung
      install.rs      # Plugin-Installation
      manage.rs       # Plugin-Auflistung und -Entfernung
      run.rs          # Plugin-Ausfuhrung

Plugin-API (api/)

api/
  crates/
    plugin-api/
      src/
        lib.rs        # Offentliche Re-Exports
        protocol.rs   # Drahtprotokoll-Typen
        entrypoints.rs # Plugin-Einstiegspunkt-Helfer
        io.rs         # JSON-stdin/stdout-Helfer
        error.rs      # Fehlertypen

Offizielle Plugins (plugins/)

plugins/
  plugins/
    animate-logo/       # Logo-Animation-Plugin
    display-resolution/ # Monitorauflosungs-Plugin
    docker/             # Docker-Statistik-Plugin
    github-stats/       # GitHub-Profil-Plugin
    music-player/       # MPD- und Spotify-Plugin
    theme-detection/    # GTK-/KDE-Theme-Plugin
    timezone/           # Zeitzonen-Plugin
    user-info/          # Benutzerkonto-Plugin
    weather/            # Wetter-Plugin

Entwicklungsworkflow

Tests ausfuhren

# Alle Tests ausfuhren
cd xfetch
cargo test

# Tests mit Ausgabe ausfuhren
cargo test -- --nocapture

# Einen bestimmten Test ausfuhren
cargo test test_name

Code-Qualitat

# Lint
cargo clippy

# Formatieren
cargo fmt

# Prufen (schnelle Kompilierung, kein Binary)
cargo check

Plugins testen

# Ein Info-Plugin uber das JSON-Protokoll testen
echo '{"version":1,"kind":"info_provider","args":null}' \
  | ./target/release/xfetch-plugin-my-plugin

# Ein Logo-Animation-Plugin testen
echo '{"version":1,"kind":"logo_animation","lines":["hello"],"args":{"fps":12}}' \
  | ./target/release/xfetch-plugin-my-plugin

Plugins schreiben

Namenskonvention

Plugin-Binaries mussen der Namenskonvention xfetch-plugin-<name> folgen, damit der Kern sie finden kann.

Plugin-Protokoll

Plugins kommunizieren mit dem xfetch-Kern uber ein JSON-Protokoll uber stdin/stdout:

  1. Der Kern schreibt eine JSON-Anfrage in das stdin des Plugins
  2. Das Plugin verarbeitet die Anfrage
  3. Das Plugin schreibt eine JSON-Antwort auf stdout
  4. Bei einem Fehler schreibt das Plugin auf stderr und beendet sich mit einem Status ungleich Null

Minimales Info-Plugin-Skelett

use xfetch_plugin_api::{
    read_info_plugin_args_or_default,
    write_info_lines,
};

#[derive(Debug, Default, serde::Deserialize)]
struct PluginArgs {}

fn main() {
    let _args = match read_info_plugin_args_or_default::<PluginArgs>() {
        Ok(value) => value,
        Err(err) => {
            eprintln!("{}", err);
            std::process::exit(1);
        }
    };

    let lines = vec!["Hello from plugin".to_string()];

    if let Err(err) = write_info_lines(lines) {
        eprintln!("{}", err);
        std::process::exit(1);
    }
}

Cargo.toml fur Plugins

[package]
name = "xfetch-plugin-my-plugin"
version = "0.1.0"
edition = "2024"

[dependencies]
serde = { version = "1", features = ["derive"] }
serde_json = "1"
xfetch-plugin-api = { git = "https://github.com/xfetch-cli/api", package = "xfetch-plugin-api" }

Plugin-Standards

  • Den gesamten Code und die Dokumentation in Englisch verfassen
  • Das gemeinsame xfetch-plugin-api-Crate fur Protokolltypen verwenden
  • Fehler explizit behandeln -- auf stderr schreiben und mit Status ungleich Null beenden
  • Keine Anzeige- oder Terminalbibliotheken verwenden (der Kern ubernimmt das Rendering)
  • Plugins auf eine einzige Verantwortung konzentrieren
  • Abhangigkeiten minimieren
  • Netzwerk- oder E/A-Fehler elegant mit informativen Meldungen behandeln

Pull-Request-Prozess

  1. Forken Sie das Repository und erstellen Sie einen Feature-Branch
  2. Implementieren Sie Ihre Anderungen gemaa den Codierungsstandards
  3. Stellen Sie sicher, dass cargo build --release erfolgreich ist
  4. Fugen Sie Tests fur neue Funktionen hinzu
  5. Fuhren Sie cargo test aus, um zu uberprufen, dass alle Tests bestanden werden
  6. Reichen Sie einen Pull-Request mit einer klaren Beschreibung Ihrer Anderungen ein

Tests

Testkategorien

Kategorie Ort Beschreibung
Unit-Tests In jeder Quelldatei Tests fur einzelne Funktionen
Integrationstests src/-Submodule Tests fur Modulinteraktionen
Plugin-Protokoll-Tests api/crates/plugin-api/src/protocol.rs Serialisierungs- und Validierungstests

Vorhandene Testabdeckung

  • Cache-System: set/get, Ablauf, fehlende Schlussel, Bereinigung
  • Konfigurations-Parsing: Modulbaum, Injektionspravention
  • Layout-Rendering: klassisch, side-block, Baum, leere Falle
  • Logo-Laden: Standard-Logo, Pfaderweiterung
  • Info-Module: Hostname, Akku, GPU, Pakete, OS, Kernel, Uptime, Datum/Uhrzeit, Benutzer, Desktop
  • Plugin-System: Benennung, Binary-Erkennung, Kandidatenverzeichnisse

Sicherheit

  • Melden Sie Sicherheitslucken an x@xscriptor.com
  • Antwortziel: innerhalb von 7 Tagen
  • Legen Sie keine Geheimnisse oder Token in Plugin-Argumenten in der Versionskontrolle offen
  • Verwenden Sie Umgebungsvariablen oder sichere Konfiguration fur sensible Daten

Lizenz

xfetch ist unter der MIT-Lizenz lizenziert. Durch Ihren Beitrag stimmen Sie zu, dass Ihre Beitrage unter derselben Lizenz lizenziert werden.