contributing

Contributing to QElectroTech

Thank you for your interest in contributing to QElectroTech! This guide explains how to get involved, from reporting bugs to writing code.

Quick links:

• Issues to work on — 30+ issues need help
• Source repository — GitHub home
• Forum — Community discussion
• CONTRIBUTING.md — Official guidelines (in repository)

Ways to Contribute

Report Bugs

Found a problem? Help us fix it:

1. Search existing issues to avoid duplicates
2. Create an issue with:
   • Clear description of the problem
   • Steps to reproduce
   • Expected vs. actual behavior
   • Your QET version and OS
   • Screenshots if helpful

Suggest Features

Have an idea? Share it:

1. Search discussions to see if it's been discussed
2. Open a discussion explaining:
   • What you want to do
   • Why it would be useful
   • Any alternative approaches

Write Documentation

Help improve this wiki and other documentation:

1. See Contributing to the Wiki
2. Help translate documentation
3. Create tutorials or guides for common workflows

Create Custom Elements

Share your element libraries with the community:

1. Learn to create elements
2. Publish on the Elements Repository
3. Join the elements maintenance team

Contribute Code

Ready to code? Follow these steps:

---

Getting Started with Code Contributions

Prerequisites

You'll need:

Programming Skills:

• C++ — QET is written in modern C++ (C++11 and later)
• Qt Framework — Qt 5.x (current stable), Qt 6.x (in active development)
• Git — Version control; essential for collaboration

Tools & Knowledge:

• Build QET from source — Able to compile the project
• CMake — Build system used by QET
• Understanding of:
  • Qt Framework fundamentals (signals/slots, widgets, models)
  • XML processing (QET uses XML for files)
  • The codebase structure

Recommended:

• Some familiarity with electrical schematics (helps understand the domain)
• Experience with open-source contribution workflow

Key Technologies

Component	Technology	Use
GUI Framework	Qt 5.x / Qt 6.x	User interface, cross-platform
Language	C++	Core application logic
Build System	CMake	Build configuration and compilation
Testing	Catch2, googletest	Unit testing framework
Documentation	Doxygen	API documentation generation
Translations	Qt Linguist	Internationalization (i18n)
File Formats	XML	Projects (.qet), elements (.elmt), titleblocks
VCS	Git	Version control (GitHub)

Setup Your Development Environment

1. Fork the repository on GitHub:

   • Visit https://github.com/qelectrotech/qelectrotech-source-mirror
   • Click "Fork" button
   • Creates your own copy

2. Clone your fork locally (with submodules):

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

3. Add upstream remote to track main repository:

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

4. Create a feature branch for your work:

   git checkout -b fix/issue-123
   # or
   git checkout -b feature/my-feature
   # Branch naming: fix/*, feature/*, docs/*, refactor/*, etc.

5. Configure Git user (if not done already):

   git config user.name "Your Name"
   git config user.email "your.email@example.com"

6. Build from source to ensure environment works:

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

Making Changes

1. Understand the issue/feature:

   • Read the GitHub issue thoroughly
   • Post a comment if unclear ("I'd like to work on this")
   • Discuss approach with maintainers for major changes

2. Write clean, maintainable code:

   • Follow code formatting: Use clang-format (configuration included)
   • One logical change per commit — don't mix unrelated fixes
   • Meaningful commit messages — explain WHY, not just WHAT
   • Comment sparingly: Only complex logic needs comments
   • Keep functions focused and small

3. Code style guidelines:

   • Naming: camelCase for variables/functions, PascalCase for classes
   • Formatting: Configured via .clang-format file (run before committing)
   • Qt conventions: Follow Qt/KDE coding standards
   • Modern C++: Use C++11/14/17 features appropriately

4. Add tests for new functionality:

   • Test framework: Catch2 or googletest
   • Write unit tests that verify your changes
   • Ensure existing tests still pass: ctest
   • Run: cmake --build . && ctest

5. Build locally & test:

   cd build
   cmake --build . --config Release
   ctest  # Run tests
   ./qelectrotech  # Test the app manually

6. Keep your branch updated with upstream:

   git fetch upstream
   git rebase upstream/main
   # or merge if you prefer: git merge upstream/main

Submitting Your Contribution

1. Push your branch to your fork:

   git push origin fix/issue-123

2. Create a Pull Request (PR) on GitHub:

   • Go to your fork → "Create Pull Request" button
   • Title: Short, descriptive (e.g., "Fix NaN coordinate handling in element loading")
   • Description: Include:
     • What problem does this solve?
     • How does your solution work?
     • Screenshots for UI changes
     • Tests added
     • Related issues: "Fixes #781" or "Closes #782"
   • Base: Set to main branch
   • Draft PR: Mark as Draft if still work-in-progress

3. Respond to feedback:

   • Maintainers will review your code
   • Address comments and suggestions
   • Push additional commits to same branch (updates PR automatically)
   • Be patient and collaborative

4. Keep PR updated if main branch changes:

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

5. Celebrate! 🎉 Once approved and merged, your contribution is part of QET

---

Code Quality & Standards

Code Formatting

QET uses clang-format for consistent code style:

# Format your files before committing
clang-format -i src/my_file.cpp
# or format all changed files
git diff --name-only | xargs clang-format -i

Documentation

• Inline comments: Only for non-obvious logic
• Function documentation: Use Doxygen style for public APIs
• Commit messages: Clear, descriptive, explain why not just what

Testing

• Unit tests: Write tests for new functionality
• Run existing tests: Ensure you don't break anything
• Test coverage: More tests = better confidence

Commit Message Guidelines

Good commit message structure:

Brief one-line summary (50 chars or less)

Longer explanation of the change. Explain the problem,
your solution, and any trade-offs or considerations.
Keep to 72 character line width.

Fixes #123

Examples:

• ✅ "Fix NaN coordinate validation on element load"
• ✅ "Add terminal strip generator feature with tests"
• ✅ "Refactor QAction management into ActionPool"
• ❌ "Fixed stuff"
• ❌ "Work in progress"

---

Review Process

1. Automatic checks run (tests, linting)
2. Maintainers review your code for:
   • Correctness
   • Code quality
   • Compatibility
   • Performance
3. Address feedback by pushing new commits
4. Merge once approved ✅

---

Code of Conduct

We're committed to providing a welcoming community. Please:

• Be respectful and constructive
• Welcome different viewpoints
• Report inappropriate behavior to maintainers
• Focus on the code, not the person

---

Questions?

• Forum — Ask the community
• Discussions — Open-ended questions
• Maintainers — Direct questions about contributions

Thank you for helping make QElectroTech better! 🎉