Contributing

​

Getting Started

​

Before You Start

1. Read the developer documentation at developers.home-assistant.io
2. Set up your development environment - See Environment Setup
3. Familiarize yourself with the codebase - Browse existing integrations and helpers
4. Check existing issues and PRs - Avoid duplicating work

​

Ways to Contribute

• Fix bugs - Check the issue tracker
• Add new integrations - Support new devices and services
• Improve existing integrations - Add features or fix issues
• Write tests - Increase code coverage
• Improve documentation - Help at home-assistant.io
• Review pull requests - Help maintain code quality

​

Contributing Code

​

1. Fork and Clone

git clone https://github.com/YOUR_USERNAME/core.git
cd core

git remote add upstream https://github.com/home-assistant/core.git

​

2. Create a Branch

# Update dev branch
git checkout dev
git pull upstream dev

# Create feature branch
git checkout -b my-feature-branch

• fix/issue-description - For bug fixes
• feature/new-feature-name - For new features
• integration/device-name - For new integrations

​

3. Make Your Changes

• Follow code style - Use ruff and pylint (see Code Quality)
• Add type hints - All functions should have type annotations
• Write docstrings - Use Google-style docstrings
• Keep it simple - Avoid unnecessary complexity
• Handle errors gracefully - Don’t let exceptions crash Home Assistant

​

4. Write Tests

# Run tests for your changes
pytest tests/components/your_component/

# Ensure tests pass and coverage is high
pytest --cov=homeassistant.components.your_component

​

5. Run Quality Checks

# Run pre-commit hooks on all files
prek run --all-files

# Or let them run automatically on commit
git add .
git commit -m "Your commit message"

​

6. Commit Your Changes

git add .
git commit -m "Add support for XYZ device

This adds integration for XYZ device using the xyz-library.
Includes support for on/off control and brightness.

Fixes #12345"

• Use present tense (“Add feature” not “Added feature”)
• First line should be 50 characters or less
• Reference issue numbers with Fixes #123 or Closes #123
• Explain what and why, not how

​

7. Push to Your Fork

git push origin my-feature-branch

​

8. Create a Pull Request

• Be descriptive and concise
• Use present tense
• Examples: “Add XYZ integration”, “Fix light brightness issue”

• Explain what your PR does
• Reference related issues
• Include testing steps
• Add screenshots or videos if relevant
• Use the provided PR template

## Proposed change
<!-- Describe the change -->

## Type of change
- [ ] Bugfix
- [ ] New integration
- [ ] New feature for existing integration
- [ ] Breaking change
- [ ] Dependency upgrade

## Additional information
<!-- Any other relevant information -->

## Checklist
- [ ] Tests have been added
- [ ] Documentation has been updated
- [ ] Example entry for configuration.yaml included

​

Pull Request Process

​

Review Process

1. Automated checks run - All CI checks must pass
2. Code review by maintainers - Be patient, maintainers are volunteers
3. Requested changes - Address feedback and push updates
4. Approval and merge - Once approved, a maintainer will merge

​

Getting Faster Reviews

• Small PRs are better - Easier to review and merge
• One change per PR - Don’t mix unrelated changes
• Good descriptions - Help reviewers understand your changes
• Respond to feedback - Be responsive and respectful
• Pass all checks - Don’t submit PRs with failing tests

​

During Review

• Amend or squash commits after review starts
• Rebase your branch
• Force push to your PR branch

• Add new commits for changes requested
• Mark conversations as resolved when addressed
• Ask for clarification if feedback is unclear
• Be patient and respectful

​

After Merge

1. Delete your branch on GitHub
2. Update your local repository:
   git checkout dev
   git pull upstream dev
   git branch -d my-feature-branch
   

​

Integration Development

​

New Integration Checklist

• Create integration directory: homeassistant/components/your_integration/
• Add manifest.json with required metadata
• Implement __init__.py with setup functions
• Add config flow for UI configuration
• Create entity platforms (e.g., light.py, sensor.py)
• Write comprehensive tests
• Add strings.json for translations
• Create services.yaml if adding services
• Update documentation

​

Integration Requirements

{
  "domain": "your_integration",
  "name": "Your Integration",
  "codeowners": ["@your-github-username"],
  "config_flow": true,
  "documentation": "https://www.home-assistant.io/integrations/your_integration",
  "requirements": ["your-library==1.0.0"],
  "iot_class": "cloud_polling",
  "version": "1.0.0"
}

​

Config Flow

from homeassistant import config_entries
from homeassistant.data_entry_flow import FlowResult
import voluptuous as vol

class YourIntegrationConfigFlow(config_entries.ConfigFlow, domain="your_integration"):
    """Handle a config flow for Your Integration."""

    VERSION = 1

    async def async_step_user(
        self, user_input: dict[str, Any] | None = None
    ) -> FlowResult:
        """Handle the initial step."""
        if user_input is None:
            return self.async_show_form(
                step_id="user",
                data_schema=vol.Schema({
                    vol.Required("host"): str,
                }),
            )

        # Validate and create entry
        return self.async_create_entry(
            title=user_input["host"],
            data=user_input,
        )

​

Code Review Guidelines

​

For Contributors

• All CI checks pass
• Tests have good coverage
• Code follows style guidelines
• Documentation is updated
• PR description is clear and complete

• Respond promptly to feedback
• Ask questions if something is unclear
• Don’t take criticism personally
• Learn from the feedback

​

What Reviewers Look For

• Correctness - Does it work as intended?
• Tests - Are there adequate tests?
• Code quality - Is it clean and maintainable?
• Performance - Does it perform well?
• Security - Are there any security concerns?
• Breaking changes - Will this break existing setups?
• Documentation - Is it properly documented?

​

Dependencies

​

Adding Dependencies

1. Add it to your integration’s manifest.json:
   {
     "requirements": ["your-library==1.2.3"]
   }
   
2. Pin to a specific version
3. Ensure the library is actively maintained
4. Check the library’s license is compatible

​

Updating Dependencies

• Test thoroughly
• Check for breaking changes in the library
• Update integration code if needed

​

Common Issues

​

Pre-commit Hooks Fail

# Run hooks manually to see details
prek run --all-files

# Fix formatting issues automatically
ruff check --fix .
ruff format .

​

Tests Fail Locally

# Ensure all dependencies are installed
uv pip install -r requirements_test_all.txt

# Run tests with verbose output
pytest -v tests/components/your_component/

​

CI Checks Fail

• Check the CI logs on GitHub
• Reproduce the failure locally
• Fix the issue and push updates

​

Merge Conflicts

# Update your branch with latest dev
git checkout dev
git pull upstream dev
git checkout my-feature-branch
git merge dev

# Resolve conflicts, then:
git add .
git commit
git push

​

Best Practices

​

Communication

• Be respectful - Everyone is volunteering their time
• Be patient - Reviews may take time
• Be clear - Explain your reasoning
• Be open to feedback - It makes the code better

​

Code Quality

• Read existing code - Learn from high-quality integrations (Platinum/Gold level)
• Keep PRs focused - One feature or fix per PR
• Write tests - They prevent regressions
• Document your code - Future you will thank you

​

Async Code

• Use async/await - Don’t block the event loop
• Await coroutines - Calling async functions without await is a bug
• Handle cancellation - Async operations can be cancelled

​

Error Handling

import logging

_LOGGER = logging.getLogger(__name__)

async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
    """Set up from a config entry."""
    try:
        await some_async_operation()
    except SomeException as err:
        _LOGGER.error("Failed to set up: %s", err)
        return False
    
    return True

​

Feature Suggestions

1. Start a discussion on GitHub
2. Explain the use case
3. Discuss implementation approaches
4. Get feedback before starting work

​

Bug Reports

1. Create an issue on GitHub
2. Provide detailed reproduction steps
3. Include relevant logs and configuration
4. Specify your Home Assistant version

​

Resources

• Developer Documentation
• Architecture Overview
• Creating Components
• Discord Chat - #devs channel
• Community Forum

​

Code of Conduct

• Be respectful and inclusive
• Welcome newcomers
• Accept constructive criticism gracefully
• Focus on what’s best for the community

​

Thank You