Contributing

Guidelines for contributing to the Home Assistant Plasmoid project

Thank you for your interest in contributing to the Home Assistant Plasmoid! This guide will help you understand the development workflow and contribution process.

Getting Started

Before contributing, familiarize yourself with:

• QML and Qt Quick fundamentals
• KDE Plasma widget development
• Home Assistant WebSocket API
• The project structure and codebase

Development Setup

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/korapp/plasma-homeassistant.git
cd plasma-homeassistant

Installing for Development

Install the plasmoid locally for testing:

# Install from package directory
plasmapkg2 -i package

# Or upgrade if already installed
plasmapkg2 -u package

After making changes, upgrade the package and restart Plasma to test:

plasmapkg2 -u package && plasmashell --replace &

Branch Strategy

The project uses a branch-based workflow with the dev branch as the primary development branch.

1. Update dev branch

   Always start by ensuring you have the latest dev branch:

   git checkout dev
   git pull origin dev
   
2. Create a feature or bugfix branch

   Create a new branch from dev using the appropriate prefix:

   For new features:

   git checkout -b feature/your-feature-name
   

   For bug fixes:

   git checkout -b bugfix/your-bugfix-name
   

   Use descriptive, lowercase names with hyphens (e.g., feature/entity-grouping, bugfix/websocket-reconnect).

3. Make your changes

   Implement your feature or fix on the branch. Make focused commits that address specific aspects of the change.

Never commit directly to the dev or main branches. Always use feature or bugfix branches.

Commit Message Guidelines

The project follows the Conventional Commits specification for commit messages. This ensures consistent history and enables automated changelog generation.

Commit Format

<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]

Commit Types

Type	Description	Example
feat	New feature	feat(entities): add support for entity grouping
fix	Bug fix	fix: resolve websocket reconnection issue
docs	Documentation changes	docs: update installation instructions
style	Code style changes (formatting, no logic change)	style: fix indentation in Client.qml
refactor	Code refactoring (no feature change)	refactor(api): simplify service call handling
perf	Performance improvements	perf: optimize state update processing
test	Adding or updating tests	test: add unit tests for entity model
chore	Maintenance tasks	chore: update dependencies

Examples

Basic commit:

git commit -m "feat(api): add new endpoint for user authentication"

Commit with scope:

git commit -m "fix(ui): resolve issue with button alignment"

Commit with body:

git commit -m "feat(notifications): add desktop notifications for entity changes

Implements notification support using the Plasma notification system.
Users can enable notifications per entity in the configuration.

Closes #42"

Breaking change:

git commit -m "feat(config)!: change configuration file format

BREAKING CHANGE: Configuration format has changed from JSON to YAML.
Existing configurations will need to be migrated."

Breaking changes should be clearly marked with ! after the type/scope and include a BREAKING CHANGE: footer.

Code Style Guidelines

Maintain consistency with the existing codebase:

QML Style

• Use 4 spaces for indentation (no tabs)
• Follow Qt QML coding conventions
• Place opening braces on the same line
• Use camelCase for property and function names
• Group related properties together
• Add comments for complex logic

Example:

QtObject {
    id: root
    property string baseUrl
    property string token
    
    function connectToServer() {
        // Connection logic here
    }
}

File Organization

• Keep components in the components/ directory
• Use descriptive file names that match the component
• Place reusable utilities in appropriate subdirectories
• Import statements at the top, grouped logically

Best Practices

• Avoid hardcoded strings; use i18n() for user-facing text
• Handle errors gracefully with appropriate error messages
• Clean up resources in Component.onDestruction
• Use property bindings instead of imperative updates when possible
• Document public APIs with comments

Testing Your Changes

Before submitting a pull request:

1. Test locally

   Install the plasmoid and verify your changes work as expected:

   plasmapkg2 -u package
   plasmashell --replace &
   

   Test all affected functionality thoroughly.

2. Check for QML errors

   Monitor the logs for any QML errors or warnings:

   journalctl --user -f | grep -i "qml\|plasmoid"
   

   Fix any errors before submitting.

3. Test different scenarios

   • Test with and without network connectivity
   • Test with invalid configurations
   • Test WebSocket reconnection
   • Test with multiple entities
   • Verify KDE Wallet integration works
4. Verify no regressions

   Ensure existing functionality still works correctly. Test:

   • Entity state updates
   • Service calls
   • Configuration changes
   • Notifications (if enabled)

Pull Request Process

When you’re ready to submit your changes:

1. Ensure branch is up to date

   Rebase your branch on the latest dev branch:

   git checkout dev
   git pull origin dev
   git checkout your-branch-name
   git rebase dev
   

   Resolve any conflicts if they occur.

2. Run final checks

   • All commits follow Conventional Commits format
   • No QML errors in logs
   • Code follows project style guidelines
   • Changes are tested locally
3. Push your branch

   git push origin your-branch-name
   
4. Create pull request

   1. Go to the GitHub repository
   2. Click New Pull Request
   3. Select dev as the base branch
   4. Select your branch as the compare branch
   5. Fill out the PR template with:
      • Clear description of changes
      • Motivation and context
      • Related issues (use Closes #123 syntax)
      • Testing performed
      • Screenshots (if UI changes)
5. Respond to feedback

   • Address review comments promptly
   • Push additional commits to your branch
   • Use conventional commit messages for fixes
   • Request re-review when ready

Pull Request Checklist

Before submitting, verify:

• Changes are based on the dev branch
• All commits use Conventional Commits format
• Code follows project style guidelines
• Changes have been tested locally
• No QML errors or warnings
• Documentation updated (if needed)
• Issue references included (if applicable)

Reporting Issues

Found a bug or have a feature request? Use the GitHub issue templates:

Bug Reports

Use the bug report template and include:

• Clear description of the bug
• Steps to reproduce
• Expected vs. actual behavior
• System information:
  • Distribution and version
  • KDE Plasma version
  • KDE Frameworks version
  • Home Assistant version
• Error messages or logs
• Screenshots (if applicable)

Example:

**Describe the bug**
Entities don't update when Home Assistant state changes.

**To Reproduce**
1. Add a light entity to the plasmoid
2. Toggle the light in Home Assistant
3. Observe that plasmoid doesn't reflect the change

**Expected behavior**
Plasmoid should show updated light state immediately.

**System:**
- Distribution: Kubuntu 24.04
- KDE Plasma: 6.0.2
- KDE Frameworks: 6.0.0
- Home Assistant: 2024.3.1

Feature Requests

Use the feature request template and include:

• Problem description or motivation
• Proposed solution
• Alternative solutions considered
• Additional context or mockups

Before submitting a feature request, search existing issues to avoid duplicates.

Code of Conduct

• Be respectful and constructive in all interactions
• Focus on what is best for the project and community
• Accept constructive criticism gracefully
• Show empathy towards other contributors

Questions?

If you have questions about contributing:

• Check existing GitHub Discussions
• Search closed issues for similar questions
• Open a new discussion for general questions

Resources

• QML Documentation
• KDE Plasma Widget Tutorial
• Home Assistant WebSocket API
• Conventional Commits Specification

Thank you for contributing to Home Assistant Plasmoid! Your efforts help make this project better for everyone.