# Contributing to OpenMOSS | 贡献指南

[English](#english) | [中文](#中文)

---

## 中文

感谢你对 OpenMOSS 的关注！在提交 PR 之前，请阅读以下指南。

### 🌿 分支策略

- **`dev`** — 后端主开发分支，所有后端功能和修复请基于此分支
- **`main`** — 稳定发布分支，由维护者从 `dev` 合并
- **`webui`** — 前端独立分支（orphan），前端相关 PR 请基于此分支

> ⚠️ 后端改动基于 `dev`，前端改动基于 `webui`，不要基于 `main`。

```bash
# 后端开发
git checkout dev
git pull origin dev
git checkout -b feat/your-feature

# 前端开发（webui 是独立的 orphan 分支，建议单独 clone）
git clone -b webui git@github.com:uluckyXH/OpenMOSS.git openmoss-webui
cd openmoss-webui
git checkout -b feat/your-ui-feature
```

### 📝 换行符

本项目统一使用 **LF (`\n`)** 换行符。请确保你的编辑器和 Git 配置不会引入 CRLF (`\r\n`)。

**推荐配置：**

```bash
git config core.autocrlf input   # macOS / Linux
git config core.autocrlf true    # Windows
```

如果你的 PR 中 diff 显示大量无关变更，很可能是换行符被替换了。可以用 `dos2unix` 修复：

```bash
# 安装: brew install dos2unix (macOS) / apt install dos2unix (Linux)
dos2unix your-file.py
```

> 项目根目录有 `.gitattributes` 文件用于强制 LF，但某些编辑器可能会绕过。

### 🚫 不要提交以下内容

| 文件 / 目录 | 原因 |
|---|---|
| `static/` | 前端编译产物，由 CI/CD 或维护者生成 |
| `data/` | 运行时数据（数据库等） |
| `config.yaml` | 包含敏感信息的本地配置 |
| `workspace/` | Agent 工作目录 |
| `__pycache__/`、`*.pyc` | Python 缓存 |
| `node_modules/` | 前端依赖 |

这些已在 `.gitignore` 中配置。如果你的 PR 中出现了这些文件，请检查你的 `.gitignore` 是否生效。

### ✅ PR 提交检查清单

提交 PR 前请确认：

- [ ] 后端 PR 基于最新的 `dev` 分支，前端 PR 基于 `webui` 分支
- [ ] 换行符为 LF（`\n`），未引入 CRLF
- [ ] 未提交编译产物（`static/`）、数据文件（`data/`）或敏感配置（`config.yaml`）
- [ ] 填写了 PR 描述，说明改动内容和原因
- [ ] Commit message 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范
- [ ] 已自测通过

### 💬 交流

- 有问题欢迎在 [Issues](https://github.com/uluckyXH/OpenMOSS/issues) 中讨论
- 大型改动建议先开 Issue 讨论方案再动手

再次感谢你的贡献！🙏

---

## English

Thank you for your interest in OpenMOSS! Please read the following guidelines before submitting a PR.

### 🌿 Branch Strategy

- **`dev`** — Backend development branch. All backend features and fixes should be based on this branch.
- **`main`** — Stable release branch. Only merged from `dev` by maintainers.
- **`webui`** — Frontend standalone branch (orphan). All frontend PRs should be based on this branch.

> ⚠️ Backend changes go to `dev`, frontend changes go to `webui`. Never base on `main`.

```bash
# Backend development
git checkout dev
git pull origin dev
git checkout -b feat/your-feature

# Frontend development (webui is an orphan branch, recommend cloning separately)
git clone -b webui git@github.com:uluckyXH/OpenMOSS.git openmoss-webui
cd openmoss-webui
git checkout -b feat/your-ui-feature
```

### 📝 Line Endings

This project uses **LF (`\n`)** line endings exclusively. Please ensure your editor and Git configuration do not introduce CRLF (`\r\n`).

**Recommended setup:**

```bash
git config core.autocrlf input   # macOS / Linux
git config core.autocrlf true    # Windows
```

If your PR diff shows a large number of unrelated changes, it's likely a line ending issue. You can fix it with `dos2unix`:

```bash
# Install: brew install dos2unix (macOS) / apt install dos2unix (Linux)
dos2unix your-file.py
```

> The project root contains a `.gitattributes` file that enforces LF, but some editors may bypass it.

### 🚫 Do Not Commit

| File / Directory | Reason |
|---|---|
| `static/` | Frontend build artifacts, generated by CI/CD or maintainers |
| `data/` | Runtime data (database, etc.) |
| `config.yaml` | Local config containing sensitive information |
| `workspace/` | Agent workspace directory |
| `__pycache__/`, `*.pyc` | Python cache |
| `node_modules/` | Frontend dependencies |

These are already configured in `.gitignore`. If they appear in your PR, please verify your `.gitignore` is working correctly.

### ✅ PR Checklist

Before submitting a PR, please confirm:

- [ ] Backend PRs based on latest `dev`, frontend PRs based on `webui`
- [ ] Line endings are LF (`\n`), no CRLF introduced
- [ ] No build artifacts (`static/`), data files (`data/`), or sensitive configs (`config.yaml`)
- [ ] PR description filled in, explaining what and why
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
- [ ] Self-tested and working

### 💬 Communication

- Feel free to discuss questions in [Issues](https://github.com/uluckyXH/OpenMOSS/issues)
- For large changes, please open an Issue first to discuss the approach

Thank you for contributing! 🙏
