From 7f5b5492ca466a19cf8ec7e131d63ddaf2ae63fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E4=B8=8D=E6=B1=82=E5=9C=A3=E5=89=91?= Date: Tue, 14 Oct 2025 10:46:10 +0800 Subject: [PATCH] =?UTF-8?q?=E5=87=86=E5=A4=87=E5=8F=91=E5=B8=83=E5=88=B0?= =?UTF-8?q?=20HACS:=20=E4=BF=AE=E5=A4=8D=E9=85=8D=E7=BD=AE=E6=96=87?= =?UTF-8?q?=E4=BB=B6=E5=92=8C=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- HACS_PUBLISHING_GUIDE.md | 202 ++++++++++++++++++++ README.md | 8 +- custom_components/JackeryHome/__init__.py | 2 +- custom_components/JackeryHome/manifest.json | 10 +- hacs.json | 3 +- prepare_release.sh | 4 +- 6 files changed, 216 insertions(+), 13 deletions(-) create mode 100644 HACS_PUBLISHING_GUIDE.md diff --git a/HACS_PUBLISHING_GUIDE.md b/HACS_PUBLISHING_GUIDE.md new file mode 100644 index 0000000..bddd444 --- /dev/null +++ b/HACS_PUBLISHING_GUIDE.md @@ -0,0 +1,202 @@ +# HACS 发布指南 + +本指南将帮助您将 JackeryHome 集成发布到 HACS (Home Assistant Community Store)。 + +## 发布前检查清单 + +### 1. 项目结构检查 +确保项目结构符合 HACS 要求： +``` +jackery_home/ +├── hacs.json # HACS 配置文件 +├── README.md # 项目主文档 +├── LICENSE # 许可证文件 +└── custom_components/ + └── JackeryHome/ + ├── __init__.py # 集成入口 + ├── manifest.json # 集成元数据 + ├── config_flow.py # 配置流程 + ├── sensor.py # 传感器实现 + ├── strings.json # 本地化字符串 + ├── translations/ # 翻译文件 + │ └── zh-Hans.json + └── README.md # 集成技术文档 +``` + +### 2. 配置文件检查 + +#### hacs.json +```json +{ + "name": "JackeryHome", + "content_in_root": false, + "render_readme": true, + "domains": [ + "jackery_home" + ], + "iot_class": "Local Push", + "homeassistant": "2024.1.0" +} +``` + +#### manifest.json +```json +{ + "domain": "jackery_home", + "name": "JackeryHome", + "codeowners": [ + "@suyulin" + ], + "config_flow": true, + "dependencies": [ + "mqtt" + ], + "documentation": "https://github.com/suyulin/jackery_home", + "issue_tracker": "https://github.com/suyulin/jackery_home/issues", + "iot_class": "local_push", + "requirements": [ + "paho-mqtt>=1.6.0" + ], + "version": "1.0.0" +} +``` + +### 3. 代码质量检查 +- [ ] 所有 Python 文件符合 PEP 8 规范 +- [ ] 没有语法错误 +- [ ] 所有导入都正确 +- [ ] 日志记录适当 +- [ ] 错误处理完善 + +## 发布步骤 + +### 步骤 1: 准备发布 +使用提供的发布脚本： +```bash +./prepare_release.sh +``` + +或手动执行以下步骤： + +1. **检查未提交的更改** + ```bash + git status + ``` + +2. **提交所有更改** + ```bash + git add . + git commit -m "准备发布到 HACS" + ``` + +3. **更新版本号** + 编辑 `custom_components/JackeryHome/manifest.json` 中的版本号 + +4. **提交版本更新** + ```bash + git add custom_components/JackeryHome/manifest.json + git commit -m "版本更新至 v1.0.0" + ``` + +### 步骤 2: 推送到 GitHub +```bash +git push origin main +``` + +### 步骤 3: 创建 Git Tag +```bash +git tag -a v1.0.0 -m "Release v1.0.0" +git push origin v1.0.0 +``` + +### 步骤 4: 创建 GitHub Release + +#### 方法一：使用 GitHub Web 界面 +1. 访问 GitHub 仓库 +2. 点击 "Releases" → "Create a new release" +3. 选择刚创建的 tag (v1.0.0) +4. 填写 Release 标题和描述 +5. 点击 "Publish release" + +#### 方法二：使用 GitHub CLI +```bash +gh release create v1.0.0 --title "v1.0.0" --notes "JackeryHome 集成首次发布" +``` + +### 步骤 5: 验证发布 +1. 检查 GitHub Release 是否创建成功 +2. 验证下载链接是否正常 +3. 测试从 HACS 安装是否正常 + +## 用户安装指南 + +### 通过 HACS 安装 +1. **添加自定义存储库** + - 打开 HACS + - 点击右上角三个点 → "自定义存储库" + - 添加仓库 URL：`https://github.com/suyulin/jackery_home` + - 类别选择：`Integration` + - 点击"添加" + +2. **安装集成** + - 在 HACS 中搜索 "JackeryHome" + - 点击"安装" + - 重启 Home Assistant + +3. **配置集成** + - 进入 **设置** → **设备与服务** → **添加集成** + - 搜索 "JackeryHome" + - 按照配置向导完成设置 + +## 常见问题 + +### Q: HACS 中找不到我的集成？ +A: 检查以下几点： +- 确保 `hacs.json` 文件存在且格式正确 +- 确保 `manifest.json` 中的 `domain` 与 `hacs.json` 中的 `domains` 匹配 +- 确保 GitHub Release 已创建 +- 等待 HACS 缓存更新（通常需要几分钟） + +### Q: 安装后集成无法加载？ +A: 检查以下几点： +- 查看 Home Assistant 日志中的错误信息 +- 确保所有依赖项已安装 +- 检查 `manifest.json` 中的 `requirements` 字段 +- 确保代码没有语法错误 + +### Q: 如何更新集成？ +A: 更新流程： +1. 修改代码 +2. 更新 `manifest.json` 中的版本号 +3. 提交更改并推送到 GitHub +4. 创建新的 Git tag 和 Release +5. 用户在 HACS 中会看到更新通知 + +## 最佳实践 + +1. **版本管理** + - 使用语义化版本控制 (SemVer) + - 每次发布都要更新版本号 + - 在 Release 中详细描述更改内容 + +2. **文档维护** + - 保持 README.md 更新 + - 提供清晰的安装和使用说明 + - 包含故障排除指南 + +3. **代码质量** + - 定期检查代码质量 + - 添加适当的错误处理 + - 使用类型提示 + +4. **用户支持** + - 及时回复 Issues + - 提供清晰的错误信息 + - 保持文档更新 + +## 相关链接 + +- [HACS 官方文档](https://hacs.xyz/) +- [Home Assistant 开发文档](https://developers.home-assistant.io/) +- [HACS 集成要求](https://hacs.xyz/docs/publish/requirements) +- [GitHub Actions 示例](https://github.com/hacs/integration/tree/main/.github/workflows) diff --git a/README.md b/README.md index c5d2e5f..24a767e 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # JackeryHome - Home Assistant 能源监控集成 [![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](https://github.com/hacs/integration) -[![GitHub Release](https://img.shields.io/github/release/suyulin/home-assistant-demo-mqtt.svg)](https://github.com/suyulin/home-assistant-demo-mqtt/releases) -[![License](https://img.shields.io/github/license/suyulin/home-assistant-demo-mqtt.svg)](LICENSE) +[![GitHub Release](https://img.shields.io/github/release/suyulin/jackery_home.svg)](https://github.com/suyulin/jackery_home/releases) +[![License](https://img.shields.io/github/license/suyulin/jackery_home.svg)](LICENSE) 这是一个 Home Assistant 自定义集成，通过 MQTT 监控太阳能、电网、电池和家庭能源数据。 @@ -39,7 +39,7 @@ 1. **添加自定义存储库** - 打开 HACS - 点击右上角三个点 → "自定义存储库" - - 添加仓库 URL：`https://github.com/suyulin/home-assistant-demo-mqtt` + - 添加仓库 URL：`https://github.com/suyulin/jackery_home` - 类别选择：`Integration` - 点击"添加" @@ -56,7 +56,7 @@ ### 方式二：手动安装 -1. 下载最新的 [Release](https://github.com/suyulin/home-assistant-demo-mqtt/releases) +1. 下载最新的 [Release](https://github.com/suyulin/jackery_home/releases) 2. 将 `custom_components/JackeryHome` 文件夹复制到你的 Home Assistant 配置目录的 `custom_components/` 文件夹中 3. 重启 Home Assistant 4. 按照上述"配置集成"步骤进行配置 diff --git a/custom_components/JackeryHome/__init__.py b/custom_components/JackeryHome/__init__.py index 18e4bce..0b9d9ac 100644 --- a/custom_components/JackeryHome/__init__.py +++ b/custom_components/JackeryHome/__init__.py @@ -7,7 +7,7 @@ from homeassistant.const import Platform _LOGGER = logging.getLogger(__name__) -DOMAIN = "energy_monitor" +DOMAIN = "jackery_home" PLATFORMS = [Platform.SENSOR] diff --git a/custom_components/JackeryHome/manifest.json b/custom_components/JackeryHome/manifest.json index 3cfe87b..d23f849 100644 --- a/custom_components/JackeryHome/manifest.json +++ b/custom_components/JackeryHome/manifest.json @@ -1,6 +1,6 @@ { "domain": "jackery_home", - "name": "jackery_home", + "name": "JackeryHome", "codeowners": [ "@suyulin" ], @@ -8,9 +8,11 @@ "dependencies": [ "mqtt" ], - "documentation": "https://github.com/suyulin/home-assistant-demo-mqtt", - "issue_tracker": "https://github.com/suyulin/home-assistant-demo-mqtt/issues", + "documentation": "https://github.com/suyulin/jackery_home", + "issue_tracker": "https://github.com/suyulin/jackery_home/issues", "iot_class": "local_push", - "requirements": [], + "requirements": [ + "paho-mqtt>=1.6.0" + ], "version": "1.0.0" } \ No newline at end of file diff --git a/hacs.json b/hacs.json index fdcc11a..6a75397 100644 --- a/hacs.json +++ b/hacs.json @@ -3,8 +3,7 @@ "content_in_root": false, "render_readme": true, "domains": [ - "energy_monitor", - "mqtt" + "jackery_home" ], "iot_class": "Local Push", "homeassistant": "2024.1.0" diff --git a/prepare_release.sh b/prepare_release.sh index f343486..75a9855 100755 --- a/prepare_release.sh +++ b/prepare_release.sh @@ -74,14 +74,14 @@ echo "✅ 准备完成！" echo "" echo "📋 下一步操作：" echo "1. 访问 GitHub 创建 Release:" -echo " https://github.com/suyulin/home-assistant-demo-mqtt/releases/new?tag=$TAG_NAME" +echo " https://github.com/suyulin/jackery_home/releases/new?tag=$TAG_NAME" echo "" echo "2. 或者使用以下命令创建 Release (需要 gh CLI):" echo " gh release create $TAG_NAME --title \"$TAG_NAME\" --notes \"Release $TAG_NAME\"" echo "" echo "3. 用户可以通过以下方式添加到 HACS:" echo " - 在 HACS 中添加自定义存储库" -echo " - URL: https://github.com/suyulin/home-assistant-demo-mqtt" +echo " - URL: https://github.com/suyulin/jackery_home" echo " - 类别: Integration" echo "" echo "4. 查看完整发布指南:"