Skip to content

Commit fcbf7ad

Browse files
wuwentaowuwentao
committed
feat(doc): add contributing guide docs
1 parent e8f127c commit fcbf7ad

File tree

3 files changed

+364
-3
lines changed

3 files changed

+364
-3
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 178 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,178 @@
1+
# Contributing Guide (English Version)
2+
3+
> [中文版点这里 / Chinese Version](./CONTRIBUTING.zh.md)
4+
5+
Thank you for contributing to this project!
6+
This guide explains how to set up your development environment (recommended: **VS Code + Dev Container**) and how to contribute code following our workflow and style rules.
7+
8+
GitHub Path: `.github/CONTRIBUTING.md`
9+
10+
---
11+
12+
## Table of Contents
13+
14+
1. [Overview](#1-overview)
15+
2. [System Requirements](#2-system-requirements)
16+
3. [Recommended Setup: Clone in Container Volume](#3-recommended-setup-clone-in-container-volume)
17+
4. [Alternative Setup: Local Clone (Not Recommended)](#4-alternative-setup-local-clone-not-recommended)
18+
5. [Windows Users (WSL2 Required)](#5-windows-users-wsl2-required)
19+
6. [China Mainland Network Mirrors](#6-china-mainland-network-mirrors)
20+
7. [Dev Container Commands & Debugging](#7-dev-container-commands--debugging)
21+
8. [Commit & Pull Request Workflow](#8-commit--pull-request-workflow)
22+
9. [Code Style, Pre-commit & Testing](#9-code-style-pre-commit--testing)
23+
10. [Issues & Community Conduct](#10-issues--community-conduct)
24+
25+
---
26+
27+
## 1. Overview
28+
29+
This project uses **VS Code + Dev Container** to provide a consistent, containerized development environment.
30+
31+
> ✅ Recommended: Use **“Dev Containers: Clone Repository in Container Volume...”** directly from VS Code to avoid permission issues.
32+
33+
---
34+
35+
## 2. System Requirements
36+
37+
- **OS:** Linux / macOS / Windows (with WSL2)
38+
- **Python:** ≥ 3.11 (for runtime inside container)
39+
- **VS Code Extensions:**
40+
- [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
41+
- [Remote - WSL](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) (Windows only)
42+
- **Docker:** Docker Desktop (with WSL2 backend) or native Docker
43+
- **Reference:** See `.devcontainer/Dockerfile` for the environment build details.
44+
45+
> ⚠️ On Windows, you **do not need** to install Python or any build tools inside WSL manually. The container environment handles everything.
46+
47+
---
48+
49+
## 3. Recommended Setup: Clone in Container Volume
50+
51+
1. Open **VS Code**.
52+
2. Press:
53+
- **Windows/Linux:** `Ctrl + Shift + P`
54+
- **macOS:** `Cmd + Shift + P`
55+
3. Type `Dev Containers: Clone Repository in Container Volume...` and press Enter.
56+
4. Enter your repository URL (e.g., `https://github.com/<org>/<repo>.git`).
57+
5. VS Code will automatically:
58+
- Clone the repository into a Docker-managed volume.
59+
- Build and open the containerized environment.
60+
61+
**Advantages:**
62+
63+
- Avoids UID/GID conflicts.
64+
- All dependencies and configs remain inside the container.
65+
66+
---
67+
68+
## 4. Alternative Setup: Local Clone (Not Recommended)
69+
70+
If you prefer cloning locally:
71+
72+
```bash
73+
git clone <repo-url>
74+
cd <repo>
75+
code .
76+
```
77+
78+
Then open via command:
79+
80+
> `Dev Containers: Open Folder in Container`
81+
82+
⚠️ May cause permission issues if your host user differs from the container user.
83+
Use at your own risk.
84+
85+
---
86+
87+
## 5. Windows Users (WSL2 Required)
88+
89+
1. Enable WSL2:
90+
```powershell
91+
wsl --install -d Ubuntu
92+
wsl --set-default-version 2
93+
```
94+
2. No need to install Python or compilers manually.
95+
Just ensure Docker Desktop (WSL2 backend) and VS Code Dev Container extensions are installed.
96+
3. Clone or open repositories **inside WSL’s Linux filesystem**:
97+
- Example path: `/home/<user>/<repo>`
98+
- Avoid using `C:\` drives to prevent performance and permission issues.
99+
100+
---
101+
102+
## 6. China Mainland Network Mirrors
103+
104+
For users in China Mainland, set mirrors before building:
105+
106+
```bash
107+
export APT_MIRROR_DOMAIN="mirrors.tuna.tsinghua.edu.cn"
108+
export PIP_MIRROR_DOMAIN="pypi.tuna.tsinghua.edu.cn"
109+
```
110+
111+
These variables are supported inside `devcontainer/Dockerfile`.
112+
113+
---
114+
115+
## 7. Dev Container Commands & Debugging
116+
117+
| Command | Description |
118+
| ---------------------------------------- | ------------------------------------ |
119+
| **Reopen in Container** | Open current folder inside container |
120+
| **Rebuild Container** | Rebuild environment |
121+
| **Clone Repository in Container Volume** | Recommended workflow |
122+
| **Show Container Log** | View build logs and errors |
123+
124+
---
125+
126+
## 8. Commit & Pull Request Workflow
127+
128+
1. Create a branch:
129+
130+
```bash
131+
git checkout -b feat/add-feature
132+
```
133+
134+
2. Follow [Conventional Commits](https://www.conventionalcommits.org/) message format:
135+
- `feat:` → New feature
136+
- `fix:` → Bug fix
137+
- `chore:` → Tooling, configs, or non-functional updates
138+
- `docs:` → Documentation only
139+
- `refactor:` → Code restructure
140+
- `test:` → Test-only changes
141+
142+
3. Example:
143+
144+
```bash
145+
feat: add user authentication
146+
chore: update pre-commit hooks
147+
fix: correct API endpoint error
148+
```
149+
150+
4. Push and open a Pull Request.
151+
GitHub Actions will validate your commit messages automatically.
152+
153+
---
154+
155+
## 9. Code Style, Pre-commit & Testing
156+
157+
- **Pre-commit** is preinstalled inside the container.
158+
- It automatically runs:
159+
- `ruff` → Linting and static analysis
160+
- `mypy` → Type checking
161+
- Fix all reported issues before committing.
162+
- Tests use `pytest` (unless specified otherwise).
163+
164+
---
165+
166+
## 10. Issues & Community Conduct
167+
168+
When opening Issues:
169+
170+
- Include steps to reproduce, logs, and your environment info.
171+
- Be respectful, concise, and follow community guidelines.
172+
173+
---
174+
175+
**File Path:**
176+
177+
- English: `.github/CONTRIBUTING.md`
178+
- Chinese: `.github/CONTRIBUTING.zh.md`

‎.github/CONTRIBUTING.zh.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# 贡献指南（中文版）
2+
3+
> [English Version](./CONTRIBUTING.md)
4+
5+
感谢你愿意为本项目贡献代码与想法！
6+
本文档介绍如何使用 **VS Code + Dev Container** 构建开发环境、在 Windows（WSL2）下配置环境、如何提交代码以及规范要求。
7+
8+
GitHub 文件路径：`.github/CONTRIBUTING.zh.md`
9+
10+
---
11+
12+
## 目录
13+
14+
1. [开发环境概述](#一-开发环境概述)
15+
2. [系统与工具要求](#二-系统与工具要求)
16+
3. [推荐方式：在容器卷中克隆仓库](#三-推荐方式在容器卷中克隆仓库)
17+
4. [备用方式：本地克隆后再在容器中打开（不推荐）](#四-备用方式本地克隆后再在容器中打开不推荐)
18+
5. [Windows 用户指南（WSL2 必须）](#五-windows-用户指南wsl2-必须)
19+
6. [中国大陆网络镜像配置](#六-中国大陆网络镜像配置)
20+
7. [Dev Container 命令与问题排查](#七-dev-container-命令与问题排查)
21+
8. [代码提交流程](#八-代码提交流程)
22+
9. [代码风格与测试规范](#九-代码风格与测试规范)
23+
10. [问题反馈与社区守则](#十-问题反馈与社区守则)
24+
25+
---
26+
27+
## 一、开发环境概述
28+
29+
本项目采用 **VS Code + Dev Container** 容器化开发环境，保证跨平台一致性。
30+
31+
> ✅ 推荐方式：在 VS Code 命令面板中执行 **“Dev Containers: Clone Repository in Container Volume...”**
32+
> 所有依赖、权限与配置均在容器中完成。
33+
34+
---
35+
36+
## 二、系统与工具要求
37+
38+
- **操作系统**：Linux / macOS / Windows（需启用 WSL2）
39+
- **Python**：最低版本 `3.11`（容器内已自动安装）
40+
- **VS Code 插件**：
41+
- Dev Containers
42+
- Remote - WSL（仅 Windows 用户）
43+
- **Docker**：Docker Desktop（启用 WSL2 backend）或原生 Docker
44+
- **配置参考**：可查看 `.devcontainer/Dockerfile` 了解镜像构建逻辑
45+
46+
> ⚠️ Windows 用户 **无需** 在 WSL 中手动安装 Python、venv 或 pip，容器会自动配置完整环境。
47+
48+
---
49+
50+
## 三、推荐方式：在容器卷中克隆仓库
51+
52+
1. 打开 **VS Code**。
53+
2. 打开命令面板：
54+
- **Windows/Linux**：`Ctrl + Shift + P`
55+
- **macOS**：`Cmd + Shift + P`
56+
3. 输入 `Dev Containers: Clone Repository in Container Volume...`，按回车执行。
57+
4. 输入仓库地址（如 `https://github.com/<org>/<repo>.git`）。
58+
5. VS Code 将自动构建并打开容器化开发环境。
59+
60+
**优点：**
61+
62+
- 避免权限冲突；
63+
- 环境与依赖完全由容器管理；
64+
- 无需本地安装任何 Python 工具。
65+
66+
---
67+
68+
## 四、备用方式：本地克隆后再在容器中打开（不推荐）
69+
70+
```bash
71+
git clone <仓库地址>
72+
cd <仓库目录>
73+
code .
74+
```
75+
76+
然后执行命令：**Dev Containers: Open Folder in Container**
77+
78+
> ⚠️ 可能出现文件权限或 UID/GID 不一致问题，请自行调整或避免此方式。
79+
80+
---
81+
82+
## 五、Windows 用户指南（WSL2 必须）
83+
84+
1. 启用 WSL2：
85+
```powershell
86+
wsl --install -d Ubuntu
87+
wsl --set-default-version 2
88+
```
89+
2. 无需在 Ubuntu 中安装 Python 或开发工具。
90+
只需确保 **Docker Desktop**（WSL2 backend）与 **VS Code Dev Containers** 插件已启用。
91+
3. 推荐仓库存放路径：
92+
- `/home/<用户名>/<repo>`
93+
- 避免放在 `C:\` 驱动器下（性能差且易出权限问题）
94+
95+
---
96+
97+
## 六、中国大陆网络镜像配置
98+
99+
构建容器前可设置镜像变量：
100+
101+
```bash
102+
export APT_MIRROR_DOMAIN="mirrors.tuna.tsinghua.edu.cn"
103+
export PIP_MIRROR_DOMAIN="pypi.tuna.tsinghua.edu.cn"
104+
```
105+
106+
这些变量在 `.devcontainer/Dockerfile` 中已支持。
107+
108+
---
109+
110+
## 七、Dev Container 命令与问题排查
111+
112+
| 命令 | 说明 |
113+
| ---------------------------------------- | -------------------- |
114+
| **Reopen in Container** | 在容器中打开当前项目 |
115+
| **Rebuild Container** | 重建开发容器 |
116+
| **Clone Repository in Container Volume** | 推荐方式 |
117+
| **Show Container Log** | 查看容器构建日志 |
118+
119+
> 构建错误可在命令面板执行：**Dev Containers: Show Container Log**
120+
121+
---
122+
123+
## 八、代码提交流程
124+
125+
1. 新建分支：
126+
127+
```bash
128+
git checkout -b feat/功能描述
129+
```
130+
131+
2. 提交信息需遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范：
132+
- `feat:` 新功能
133+
- `fix:` 修复问题
134+
- `chore:` 工具/配置调整（如 CI/CD、pre-commit 等）
135+
- `docs:` 文档修改
136+
- `refactor:` 重构代码
137+
- `test:` 测试相关修改
138+
139+
3. 示例：
140+
141+
```bash
142+
feat: 增加登录接口
143+
chore: 更新 pre-commit 配置
144+
fix: 修复配置路径错误
145+
```
146+
147+
4. 推送并创建 Pull Request。
148+
GitHub Actions 会自动验证 commit message 格式。
149+
150+
---
151+
152+
## 九、代码风格与测试规范
153+
154+
- 容器内已预装 **pre-commit**，提交时会自动运行以下工具：
155+
- `ruff`：代码检查
156+
- `mypy`：类型检查
157+
- 若 pre-commit 报错，请根据提示修复后重新提交。
158+
- 测试推荐使用 `pytest`。
159+
160+
---
161+
162+
## 十、问题反馈与社区守则
163+
164+
- 提交 Issue 时请附带：重现步骤、环境说明、日志。
165+
- 保持尊重、清晰、建设性的沟通。
166+
167+
---
168+
169+
**文件路径：**
170+
171+
- 中文版：`.github/CONTRIBUTING.zh.md`
172+
- 英文版：`.github/CONTRIBUTING.md`

‎README.md‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ This library is part of https://github.com/georgezhao2010/midea_ac_lan code. It
1313

1414
### Finding your device
1515

16-
```python
16+
```python3
1717
from midealocal.discover import discover
1818
# Without knowing the ip address
1919
discover()
@@ -25,7 +25,7 @@ type_code = hex(list(discover().values())[0]['type'])[2:]
2525

2626
### Getting data from device
2727

28-
```python
28+
```python3
2929
from midealocal.discover import discover
3030
from midealocal.devices import device_selector
3131

@@ -43,7 +43,7 @@ ac = device_selector(
4343
port=d['port'],
4444
token=token,
4545
key=key,
46-
protocol=d['protocol'],
46+
device_protocol=d['protocol'],
4747
model=d['model'],
4848
subtype=0,
4949
customize="",
@@ -59,3 +59,14 @@ ac.set_target_temperature(23.0, None)
5959
# Setting the swing
6060
ac.set_swing(False, False)
6161
```
62+
63+
### command line tool
64+
65+
```python3
66+
python3 -m midealocal.cli -h
67+
```
68+
69+
## Contributing Guide
70+
71+
[CONTRIBUTING](.github/CONTRIBUTING.md)
72+
[中文版CONTRIBUTING](.github/CONTRIBUTING.zh.md)

0 commit comments

Comments
 (0)