Xiaomi Home Integration for Home Assistant开发管理制度

### 1.1 文档目的本文档旨在规范Xiaomi Home Integration for Home Assistant项目的开发流程、代码规范、贡献机制及质量保障措施，确保项目开发的有序性、代码质量的稳定性和功能的可靠性。### 1.2 适用范围本文档适用于所有参与Xiaomi Home Integration for Home Assistant项目开发、测试、文档编写及维护的人...

水珊习Gale

296人浏览 · 2025-09-11 04:08:58

水珊习Gale · 2025-09-11 04:08:58 发布

Xiaomi Home Integration for Home Assistant开发管理制度

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home

1. 引言

1.1 文档目的

本文档旨在规范Xiaomi Home Integration for Home Assistant项目的开发流程、代码规范、贡献机制及质量保障措施，确保项目开发的有序性、代码质量的稳定性和功能的可靠性。

1.2 适用范围

本文档适用于所有参与Xiaomi Home Integration for Home Assistant项目开发、测试、文档编写及维护的人员。

1.3 项目概述

Xiaomi Home Integration for Home Assistant（以下简称"本项目"）是一个开源项目，旨在实现小米智能家居设备与Home Assistant平台的无缝集成。项目采用Python语言开发，遵循Home Assistant的集成规范，提供对小米IoT设备的本地控制和云控制支持。

2. 开发环境搭建

2.1 环境要求

Python 3.9+
Home Assistant Core 2021.11+
Git
小米智能家居设备（用于测试）

2.2 项目克隆

git clone https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home.git
cd ha_xiaomi_home

2.3 依赖安装

pip install -r requirements.txt

2.4 开发配置

将项目添加到Home Assistant的自定义组件目录：

ln -s $(pwd)/custom_components/xiaomi_home ~/.homeassistant/custom_components/

配置Home Assistant以启用调试日志：

# configuration.yaml
logger:
  default: critical
  logs:
    custom_components.xiaomi_home: debug

3. 代码规范

3.1 命名规范

3.1.1 项目特定命名

实体	规范名称	变量命名	示例
小米	Xiaomi	xiaomi, mi	xiaomi_home, miot_device
米家	Xiaomi Home	mihome, MiHome	mihome_api, MiHomeDevice
小米IoT	MIoT	miot, MIoT	miot_client, MIoTSpec
Home Assistant	Home Assistant	hass, hass_xxx	hass_config, hass_entity

3.1.2 通用命名

类名使用PascalCase，如MIoTDevice
函数和变量使用snake_case，如async_setup_entry
常量使用全大写SNAKE_CASE，如DEFAULT_TIMEOUT
文件名使用snake_case，如miot_client.py

3.2 代码风格

项目遵循Google Python风格指南，主要要求包括：

使用4个空格缩进，不使用制表符
每行代码不超过88个字符
函数和类之间空两行
导入顺序：标准库 > 第三方库 > 项目内部导入

3.3 代码检查

提交代码前需运行以下工具进行检查：

# 代码风格检查
pylint custom_components/xiaomi_home

# 代码格式化
black custom_components/xiaomi_home

# 类型检查
mypy custom_components/xiaomi_home

4. 开发流程

4.1 分支管理

项目采用Git Flow工作流，主要分支包括：

main: 主分支，保持稳定可发布状态
develop: 开发分支，包含最新开发特性
feature/*: 功能分支，用于开发新功能
bugfix/*: 修复分支，用于修复bug
release/*: 发布分支，用于版本发布准备

4.2 开发流程

mermaid

从develop分支创建功能分支：feature/awesome-feature
在功能分支上进行开发，提交遵循提交规范
编写单元测试，确保代码覆盖率>80%
创建Pull Request到develop分支
通过代码审查后合并
定期从develop分支发布测试版本
发布稳定版本时，从develop创建release分支，测试通过后合并到main

4.3 提交规范

提交信息应遵循以下格式：

<type>: <subject>

<body>

<footer>

4.3.1 Type类型

feat: 新功能
fix: 错误修复
docs: 文档更新
style: 代码格式调整（不影响代码逻辑）
refactor: 代码重构
perf: 性能优化
test: 添加或修改测试
chore: 构建过程或辅助工具变动
revert: 回滚先前的提交

4.3.2 示例

feat: 添加小米空气净化器控制

实现了对小米空气净化器的风速调节和模式切换功能。

- 新增MIoTProperty类处理设备属性
- 添加fan.py实现风扇控制实体

Closes #123

5. 功能开发规范

5.1 设备集成流程

mermaid

5.2 核心组件开发

5.2.1 设备类实现

设备类应继承MIoTDevice基类，并实现特定设备的属性和方法：

class XiaomiAirPurifier(MIoTDevice):
    def __init__(self, miot_device: MIoTDevice, entity_data: MIoTEntityData):
        super().__init__(miot_device, entity_data)
        self._fan_speed = None
        self._mode = None

    @property
    def fan_speed(self) -> Optional[int]:
        return self._fan_speed

    async def async_set_fan_speed(self, speed: int) -> None:
        await self.set_property_async(self._props["fan_speed"], speed)

5.2.2 实体组件开发

实体组件应实现Home Assistant的相应接口，如async_setup_entry：

async def async_setup_entry(
    hass: HomeAssistant,
    config_entry: ConfigEntry,
    async_add_entities: AddEntitiesCallback,
) -> None:
    """设置小米空气净化器实体"""
    miot_device = hass.data[DOMAIN][config_entry.entry_id]
    entity_data = miot_device.parse_miot_service_entity("fan")
    async_add_entities([XiaomiAirPurifierFan(miot_device, entity_data)])

6. 测试规范

6.1 测试类型

单元测试：测试独立函数和类
集成测试：测试组件间交互
功能测试：测试完整功能流程
性能测试：测试设备响应时间和资源占用

6.2 测试实现

测试文件位于test/目录下，使用pytest框架：

# test_miot_client.py
import pytest
from custom_components.xiaomi_home.miot.miot_client import MIoTClient

@pytest.mark.asyncio
async def test_miot_client_connect():
    client = MIoTClient("test_did", "test_token")
    assert await client.connect() is True

6.3 测试执行

# 运行所有测试
pytest test/

# 运行特定测试文件
pytest test/test_miot_client.py

# 生成测试覆盖率报告
pytest --cov=custom_components.xiaomi_home test/

7. 文档规范

7.1 文档类型

README.md: 项目概述和快速开始
CONTRIBUTING.md: 贡献指南
功能文档: 位于doc/目录，如README_zh.md
代码注释: 为所有公共API和复杂逻辑提供文档字符串

7.2 文档格式

使用Markdown格式
中英文之间添加空格
技术术语首次出现时提供中英文对照，如"物联网（Internet of Things, IoT）"
使用代码块展示配置示例和命令
使用表格展示复杂信息
使用mermaid图表展示流程和架构

7.3 示例文档

# 小米空气净化器集成

## 功能概述

支持小米空气净化器的开关控制、风速调节和模式切换。

## 配置示例

```yaml
fan:
  - platform: xiaomi_home
    name: "我的空气净化器"
    did: "1234567890"

使用方法

服务调用

服务	描述	参数
xiaomi_home.set_fan_speed	设置风速	speed: 1-100


## 8. 贡献流程

### 8.1 贡献类型

- 代码贡献：新功能、bug修复、性能优化
- 文档贡献：文档翻译、教程编写
- 测试贡献：编写测试用例、报告bug
- 反馈贡献：使用体验反馈、功能建议

### 8.2 Pull Request流程

1. Fork项目仓库
2. 创建功能分支：`git checkout -b feature/amazing-feature`
3. 提交更改：`git commit -m 'feat: add amazing feature'`
4. 推送到分支：`git push origin feature/amazing-feature`
5. 创建Pull Request

### 8.3 Pull Request要求

- 单个PR只解决一个问题或实现一个功能
- 代码符合项目编码规范
- 包含必要的测试用例
- 更新相关文档
- PR描述清晰，包含实现细节和测试方法

## 9. 版本管理

### 9.1 版本号格式

采用[语义化版本](https://semver.org/)：`主版本.次版本.修订号`

- 主版本：不兼容的API变更
- 次版本：向后兼容的功能新增
- 修订号：向后兼容的问题修复

### 9.2 发布流程

1. 更新CHANGELOG.md，记录版本变更内容
2. 创建版本标签：`git tag -a v1.2.0 -m "Version 1.2.0"`
3. 推送标签：`git push origin v1.2.0`
4. 在GitCode上创建发布，包含详细的变更说明和二进制资产

## 10. 质量保障

### 10.1 代码审查 checklist

- [ ] 代码符合项目编码规范
- [ ] 包含适当的测试用例
- [ ] 文档已更新
- [ ] 所有测试通过
- [ ] 不引入新的警告
- [ ] 性能影响已评估

### 10.2 持续集成

项目使用GitHub Actions进行持续集成：

- 代码风格检查
- 单元测试
- 集成测试
- 文档构建

## 11. 知识产权

### 11.1 许可协议

项目采用Apache License 2.0许可协议，详见LICENSE.md。

### 11.2 贡献者许可协议

首次提交Pull Request时，贡献者需要签署贡献者许可协议（CLA），确认贡献内容的知识产权归属。

## 12. 违规处理

对于违反本管理制度的行为，项目维护者可采取以下措施：

- 要求修改不符合规范的代码
- 关闭不符合要求的Pull Request
- 暂停严重或重复违规者的贡献权限

## 13. 附则

### 13.1 制度更新

本管理制度会根据项目发展情况定期更新，所有贡献者应关注最新版本。

### 13.2 解释权

本管理制度的最终解释权归项目维护团队所有。

### 13.3 联系方式

- 项目讨论区：项目的GitHub Discussions
- 电子邮件：ha_xiaomi_home@xiaomi.com

【免费下载链接】ha_xiaomi_home Xiaomi Home Integration for Home Assistant 项目地址: https://gitcode.com/gh_mirrors/ha/ha_xiaomi_home