Skip to content

contributing DE

Jump to bottom Edit New page
ispyisail edited this page Sep 9, 2026 · 1 revision

Zu QElectroTech Beitragen

Vielen Dank für Ihr Interesse, zu QElectroTech beizutragen ! Dieser Leitfaden erklärt, wie Sie sich einbringen können, von Fehlermeldungen bis zum Schreiben von Code.

Schnelllinks :

Wege zum Beitragen

Bugs Melden

Sie haben ein Problem gefunden? Helfen Sie uns, es zu beheben:

  1. Suchen Sie nach vorhandenen Problemen um Duplikate zu vermeiden
  2. Erstellen Sie ein Problem mit :
    • Klare Problembeschreibung
    • Schritte zum Reproduzieren
    • Erwartetes vs. tatsächliches Verhalten
    • Ihre QET-Version und Betriebssystem
    • Screenshots falls hilfreich

Funktionen Vorschlagen

Haben Sie eine Idee ? Teilen Sie sie :

  1. Suchen Sie nach Diskussionen um zu sehen, ob sie bereits diskutiert wurde
  2. Öffnen Sie eine Diskussion und erklären :
    • Was Sie tun möchten
    • Warum es nützlich wäre
    • Beliebige alternative Ansätze

Dokumentation Schreiben

Helfen Sie, dieses Wiki und andere Dokumentationen zu verbessern :

  1. Siehe Zum Wiki Beitragen
  2. Hilf bei der Übersetzung der Dokumentation
  3. Erstellen Sie Tutorials oder Guides für häufige Workflows

Benutzerdefinierte Elemente Erstellen

Teilen Sie Ihre Element-Bibliotheken mit der Gemeinschaft :

  1. Erfahren Sie, wie Sie Elemente erstellen
  2. Veröffentlichen Sie auf dem Elements-Repository
  3. Treten Sie dem Elements-Wartungs-Team bei

Code Beitragen

Bereit zu codieren? Folgen Sie diesen Schritten :

Erste Schritte mit Code-Beiträgen

Voraussetzungen

Sie benötigen :

Programmierfähigkeiten :

  • C++ — QET ist in modernem C++ geschrieben (C++11 und später)
  • Qt-Framework — Qt 5.x (aktuell stabil), Qt 6.x (aktiv in Entwicklung)
  • Git — Versionskontrolle ; essentiell für Zusammenarbeit

Werkzeuge und Wissen :

  • QET aus Quelle erstellen — Das Projekt kompilieren können
  • CMake — Von QET verwendetes Build-System
  • Verständnis von :
    • Qt-Framework-Grundlagen (Signale/Slots, Widgets, Modelle)
    • XML-Verarbeitung (QET verwendet XML für Dateien)
    • Die Codebase-Struktur

Empfohlen :

  • Gewisse Vertrautheit mit Stromlaufplänen (hilft, die Domäne zu verstehen)
  • Erfahrung mit Open-Source-Beitrags-Workflows

Schlüsseltechnologien

Komponente Technologie Verwendung
GUI-Framework Qt 5.x / Qt 6.x Benutzeroberfläche, plattformübergreifend
Sprache C++ Logik der Kern-Anwendung
Build-System CMake Konfiguration und Kompilierung
Tests Catch2, googletest Unit-Test-Framework
Dokumentation Doxygen API-Dokumentations-Generierung
Übersetzungen Qt Linguist Internationalisierung (i18n)
Dateiformate XML Projekte (.qet), Elemente (.elmt), Titelblöcke
VCS Git Versionskontrolle (GitHub)

Konfigurieren Sie Ihre Entwicklungsumgebung

  1. Forken Sie das Repository auf GitHub :

  2. Klonen Sie Ihren Fork lokal (mit Submodulen) :

    git clone --recursive https://github.com/IHR_BENUTZERNAME/qelectrotech-source-mirror.git
cd qelectrotech-source-mirror

  3. Fügen Sie Remote-Upstream hinzu um das Haupt-Repository zu verfolgen :

    git remote add upstream https://github.com/qelectrotech/qelectrotech-source-mirror.git

  4. Erstellen Sie einen Feature-Branch für Ihre Arbeit :

    git checkout -b fix/issue-123
# oder
git checkout -b feature/mein-feature
# Branch-Benennung : fix/*, feature/*, docs/*, refactor/*, etc.

  5. Konfigurieren Sie Git-Benutzer (falls noch nicht geschehen) :

    git config user.name "Ihr Name"
git config user.email "ihre.email@beispiel.com"

  6. Aus Quelle erstellen um sicherzustellen, dass die Umgebung funktioniert :

    mkdir build && cd build
cmake ..
cmake --build . --config Release

Änderungen Anbringen

  1. Problem/Funktion verstehen :

    • GitHub-Problem gründlich lesen
    • Kommentar posten falls unklar ("Ich möchte daran arbeiten")
    • Ansatz mit Verantwortlichen für größere Änderungen besprechen

  2. Sauberen, wartbaren Code schreiben :

    • Code-Formatierung befolgen : clang-format verwenden (Konfiguration enthalten)
    • Eine logische Änderung pro Commit — keine unzusammenhängenden Fixes mischen
    • Aussagekräftige Commit-Nachrichten — WARUM erklären, nicht nur WAS
    • Sparsam kommentieren : Nur komplexe Logik benötigt Kommentare
    • Funktionen konzentriert und klein halten

  3. Code-Stil-Richtlinien :

    • Benennung : camelCase für Variablen/Funktionen, PascalCase für Klassen
    • Formatierung : Konfiguriert über .clang-format-Datei (vor dem Commit ausführen)
    • Qt-Konventionen : Qt/KDE-Kodierungsstandards befolgen
    • Modernes C++ : C++11/14/17-Funktionen angemessen verwenden

  4. Tests für neue Funktionalität hinzufügen :

    • Test-Framework : Catch2 oder googletest
    • Unit-Tests schreiben, die Ihre Änderungen verifizieren
    • Sicherstellen, dass vorhandene Tests immer noch bestanden werden : ctest
    • Ausführen : cmake --build . && ctest

  5. Lokal erstellen und testen :

    cd build
cmake --build . --config Release
ctest  # Tests ausführen
./qelectrotech  # App manuell testen

  6. Halten Sie Ihren Branch mit Upstream aktuell :

    git fetch upstream
git rebase upstream/main
# oder zusammenführen, wenn Sie bevorzugen : git merge upstream/main

Reichen Sie Ihren Beitrag ein

  1. Pushen Sie Ihren Branch zu Ihrem Fork :

    git push origin fix/issue-123

  2. Erstellen Sie einen Pull Request (PR) auf GitHub :

    • Gehen Sie zu Ihrem Fork → "Pull Request erstellen"-Schaltfläche
    • Titel : Kurz, beschreibend (z. B. "NaN-Koordinatenvalidierung beim Element-Laden beheben")
    • Beschreibung : Einschließen :
      • Welches Problem löst dies?
      • Wie funktioniert Ihre Lösung?
      • Screenshots für UI-Änderungen
      • Hinzugefügte Tests
      • Verwandte Probleme : "Fixes #781" oder "Closes #782"
    • Base : Auf den main-Branch setzen
    • Draft PR : Als Entwurf markieren, falls noch in Bearbeitung

  3. Reagieren Sie auf Feedback :

    • Betreuer werden Ihren Code überprüfen
    • Kommentare und Vorschläge adressieren
    • Zusätzliche Commits zum gleichen Branch pushen (aktualisiert PR automatisch)
    • Seien Sie geduldig und zusammenarbeitend

  4. Halten Sie PR aktuell, falls sich der Main-Branch ändert :

    git fetch upstream
git rebase upstream/main
git push --force-with-lease origin fix/issue-123

  5. Feiern Sie ! 🎉 Einmal genehmigt und zusammengeführt, ist Ihr Beitrag Teil von QET

Code-Qualität und Normen

Code-Formatierung

QET verwendet clang-format für konsistenten Code-Stil :

# Formatieren Sie Ihre Dateien vor dem Commit
clang-format -i src/meine_datei.cpp
# oder formattieren Sie alle geänderten Dateien
git diff --name-only | xargs clang-format -i

Dokumentation

  • Inline-Kommentare : Nur für nicht offensichtliche Logik
  • Funktions-Dokumentation : Doxygen-Stil für öffentliche APIs verwenden
  • Commit-Nachrichten : Klar, beschreibend, erklären warum nicht nur was

Tests

  • Unit-Tests : Tests für neue Funktionalität schreiben
  • Vorhandene Tests ausführen : Sicherstellen, dass Sie nichts kaputt machen
  • Test-Abdeckung : Mehr Tests = besseres Vertrauen

Commit-Nachrichten-Richtlinien

Gute Commit-Nachrichten-Struktur :

Knappe Zusammenfassung in einer Zeile (50 Zeichen oder weniger)

Längere Erklärung der Änderung. Erklären Sie das Problem,
Ihre Lösung und alle Kompromisse oder Überlegungen.
Halten Sie sich an eine Linienbreite von 72 Zeichen.

Fixes #123

Beispiele :

  • ✅ "NaN-Koordinaten-Validierung beim Element-Laden beheben"
  • ✅ "Leiter-Streifen-Generator-Funktion mit Tests hinzufügen"
  • ❌ "Bug beheben"
  • ❌ "Code aktualisieren"

Code-Überprüfung

  • Betreuer werden Ihren Code überprüfen
  • Kommentare zielen auf Verbesserung, nicht auf persönliche Kritik ab
  • Seien Sie offen für Vorschläge
  • Fragen Sie um Klarstellung, falls etwas unklar ist

Ressourcen und Hilfe

Wo Sie Hilfe Finden

Kommunikation

  • Seien Sie respektvoll — Wir sind alle hier um QET zu verbessern
  • Seien Sie klar — Erklären Sie, was Sie erreichen möchten
  • Fragen Sie um Hilfe — Keine Angst vor Fragen
  • Würdigen Sie Beiträge — Anerkennen Sie die Arbeit anderer

Danke dass Sie Beitragen ! 🎉

Ihre Beiträge helfen QElectroTech ein besseres Werkzeug für alle zu werden. Sei es ein Bug-Fix, eine neue Funktion, Dokumentation oder eine Übersetzung, Ihre Arbeit wird geschätzt !

Fragen ? Treten Sie dem Forum bei oder stellen Sie eine Frage auf GitHub-Diskussionen.

🌐 Sprache wählen — English · Français · Deutsch

Home tools

qelectrotech

Getting Started

Home

🌐 Languages — English · Français · Deutsch

Downloads

Windows without admin rights — the portable archive, no installer

Quick Start Guide

User Manual

FAQ

Tips & Tricks

Guides

Conductors — wire properties, what feeds which export, cables, and hops where wires cross

Wires per terminal — limit the wires on a terminal, chain wiring instead of stars

Printing and exporting — paper, PDF, images, and what each path does differently

Linking elements — master, slave, terminal

PLC modules — I/O tables and linking a wire to a specific point

Using the element editor — drawing tools, saving, checks

Grid size and element size — why symbols aren't all the same scale, and scaling one without leaving the grid

Preferences reference — what each settings page does

Saving and loading settings — your whole setup in one file, to copy or keep

Keyboard-only control — mouseless QET, and what still needs a mouse

Mouse modifiers — what Shift, Ctrl and Alt change while you drag

3D mouse — SpaceMouse pan, zoom and buttons

Aligning items — snap symbols back to the grid, or line them up

Pictures on a sheet — labels, crop, transparency, what they cost in the file

Arcs and curved wires — the Arc tool, pulling an arc in or out, rounding a corner with a fillet, dashed arcs for lighting layouts

Grouping items — select, move and copy several items as one

Finding your place on a sheet — go to a cell like B13 or 4-B7, keep the headers in sight, show the cell limits, zoom and pan

Showing and hiding kinds of items — hide texts, wire numbers, shapes, pictures, tables or cross-references on every sheet

Drawing faster — place without dragging, the S shortcut bar, command search, gestures

Customising QElectroTech — keys, toolbar size and contents, the gesture ring (partly pending)

Managing collections — folders, writability, building your own shortlist

Templates — reusable multi-element blocks, placed by double-click or drag

Search & Replace — bulk property changes

Building a nomenclature query — the BOM/summary table builder

Linking wires across pages — sheet reports

Variables & formulas — %f, %{label}, sequences

Auto-numbering — schemes, sequences, freezing

Terminal strips — strips, levels, bridges

Title block templates — the .titleblock format

Importing EPLAN parts (.edz) — EPLAN Data Portal

DXF import & export — two unrelated features, one format; command-line export and layers

The project database — the in-memory SQLite cache

File formats
Elements XML
Project XML
Development

Building from Source

Contributing Code

Automating QET — CLI, XML formats, external tools

CLI Reference — command line usage

JavaScript Scripting — --run, geometry editing, undo

MCP server — let an AI assistant read, verify and edit projects

Connecting an AI assistant — setup for Claude, Copilot, Gemini, Codex, Cursor, LM Studio

Script buttons — stored scripts with an icon, by hand or by an assistant

Live mode — an assistant working in the open project while you watch

Macro recorder — record a task by hand, for an assistant to script

Development Roadmap

Vision — proposal, under discussion

Developer Tools

About

Features

History

Community

License

Contributing to this Wiki

Clone this wiki locally