> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/home-assistant/core/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing

> How to contribute to Home Assistant Core

Everybody is invited and welcome to contribute to Home Assistant. Whether you're a developer, designer, or technical writer, there's always something you can help with.

## Getting Started

### Before You Start

1. **Read the developer documentation** at [developers.home-assistant.io](https://developers.home-assistant.io/)
2. **Set up your development environment** - See [Environment Setup](/development/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](https://github.com/home-assistant/core/issues)
* **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](https://home-assistant.io/)
* **Review pull requests** - Help maintain code quality

## Contributing Code

### 1. Fork and Clone

Fork the [home-assistant/core](https://github.com/home-assistant/core) repository on GitHub, then clone your fork:

```bash theme={null}
git clone https://github.com/YOUR_USERNAME/core.git
cd core
```

Add upstream remote:

```bash theme={null}
git remote add upstream https://github.com/home-assistant/core.git
```

### 2. Create a Branch

Create a branch for your work from the `dev` branch:

```bash theme={null}
# Update dev branch
git checkout dev
git pull upstream dev

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

Branch naming suggestions:

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

### 3. Make Your Changes

Write your code following these guidelines:

* **Follow code style** - Use ruff and pylint (see [Code Quality](/development/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

All code changes must include tests:

```bash theme={null}
# Run tests for your changes
pytest tests/components/your_component/

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

See [Testing](/development/testing) for detailed guidance.

### 5. Run Quality Checks

Before committing, run all quality checks:

```bash theme={null}
# 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"
```

Fix any issues that arise. See [Code Quality](/development/code-quality) for details.

### 6. Commit Your Changes

Write clear, descriptive commit messages:

```bash theme={null}
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"
```

**Commit message guidelines:**

* 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

```bash theme={null}
git push origin my-feature-branch
```

### 8. Create a Pull Request

Create a pull request against the **`dev`** branch of home-assistant/core.

**Pull request title:**

* Be descriptive and concise
* Use present tense
* Examples: "Add XYZ integration", "Fix light brightness issue"

**Pull request description:**

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

**PR template sections:**

```markdown theme={null}
## 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

Read [How to get faster PR reviews](https://github.com/kubernetes/community/blob/master/contributors/guide/pull-requests.md#best-practices-for-faster-reviews) by Kubernetes (skip steps 0-1).

**Key points:**

* **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

**Do NOT:**

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

Reviewers need to see what changed since their last review.

**DO:**

* 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

Once merged:

1. **Delete your branch** on GitHub
2. **Update your local repository**:
   ```bash theme={null}
   git checkout dev
   git pull upstream dev
   git branch -d my-feature-branch
   ```

## Integration Development

### New Integration Checklist

When adding a new integration:

* [ ] 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

**manifest.json** must include:

```json theme={null}
{
  "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

New integrations should use config flows for UI-based setup:

```python theme={null}
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

**Before requesting review:**

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

**During review:**

* 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

When adding a new Python library:

1. Add it to your integration's `manifest.json`:
   ```json theme={null}
   {
     "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

When updating dependency versions:

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

## Common Issues

### Pre-commit Hooks Fail

```bash theme={null}
# Run hooks manually to see details
prek run --all-files

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

### Tests Fail Locally

```bash theme={null}
# 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

```bash theme={null}
# 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

```python theme={null}
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

If you want to suggest a new feature:

1. [Start a discussion](https://github.com/orgs/home-assistant/discussions) on GitHub
2. Explain the use case
3. Discuss implementation approaches
4. Get feedback before starting work

## Bug Reports

If you find a bug:

1. [Create an issue](https://github.com/home-assistant/core/issues) on GitHub
2. Provide detailed reproduction steps
3. Include relevant logs and configuration
4. Specify your Home Assistant version

## Resources

* [Developer Documentation](https://developers.home-assistant.io/)
* [Architecture Overview](https://developers.home-assistant.io/docs/architecture_index/)
* [Creating Components](https://developers.home-assistant.io/docs/creating_component_index/)
* [Discord Chat](https://www.home-assistant.io/join-chat/) - #devs channel
* [Community Forum](https://community.home-assistant.io/)

## Code of Conduct

Home Assistant has a [Code of Conduct](https://github.com/home-assistant/core/blob/dev/CODE_OF_CONDUCT.md). All contributors are expected to follow it.

Key points:

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

## Thank You

Thank you for contributing to Home Assistant! Your contributions help millions of users create smarter homes with local control and privacy. Every contribution, no matter how small, makes a difference.