arch-configs/dot_local/share/plasma/plasmoids/org.kde.plasma.kvitals/docs/contributing.md

Contributing

Thanks for your interest in contributing to KVitals!

Getting Started

1. Fork the repository
2. Clone your fork:

   git clone https://github.com/<your-username>/kvitals.git
   cd kvitals
   

3. Install locally for development:

   bash install.sh
   

Development Workflow

Making Changes

1. Edit files in the project directory
2. Reinstall and test:

   bash install.sh
   kquitapp6 plasmashell && kstart plasmashell &
   

3. Check for QML errors:

   journalctl -b --no-pager | grep kvitals
   

!!! tip "Fast Iteration" You don't always need to restart plasmashell. For config-only changes, just reopen the settings dialog. For QML changes, a restart is required.

Adding a New Metric

1. Sensors — Find the relevant org.kde.ksysguard.sensors sensor ID using kstatsviewer
2. Settings — Add show* and compactShow* entries to contents/config/main.xml
3. Configuration UI — Add the metric and compact visibility checkboxes to configMetrics.qml
4. Icons — Add an icon picker to configIcons.qml
5. UI — Add property bindings and model entries in main.qml

!!! note Don't forget to add a default icon name for the new metric in configIcons.qml's reset button handler.

Adding a New Setting

1. Add the entry to contents/config/main.xml with a default value
2. Add the UI control to the appropriate config tab (configGeneral.qml, configMetrics.qml, configIcons.qml, or configColors.qml)
3. Bind the value in main.qml via Plasmoid.configuration.<key>

Pull Requests

1. Create a feature branch: git checkout -b feat/my-feature
2. Make your changes and test locally
3. Ensure ShellCheck passes
4. Push and open a PR against master

!!! tip "Commit Messages" Use conventional commits for clear history:

- `feat:` — New feature
- `fix:` — Bug fix
- `chore:` — Maintenance
- `docs:` — Documentation

Code Style

• QML — Follow KDE's QML conventions, use Kirigami components where possible
• Commits — Use conventional commits: feat:, fix:, chore:, docs:

Reporting Issues

When filing a bug report, please include:

• KDE Plasma version (plasmashell --version)
• Linux distribution and version
• Whether you're using Intel or AMD CPU
• Relevant journal output (journalctl -b | grep kvitals)

!!! note "Debugging Output" To capture detailed logs for a bug report: bash journalctl -b --no-pager | grep -i "kvitals\|sys-state" > kvitals-debug.log