Metadata-Version: 2.1
Name: openkylin-contrib-helper
Version: 0.1.0
Summary: openKylin社区贡献助手 - CLI工具
License: MulanPSL-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE

# openkylin-contrib-helper

openKylin 社区贡献助手 — CLI 工具，帮助新手快速参与开源贡献。

## 环境要求

- Python ≥ 3.10
- Gitee 账号及 [Personal Access Token](https://gitee.com/profile/personal_access_tokens)（需要 `projects`、`user_info` 权限）

## 安装

### 方式一：源码安装（推荐）

```bash
# 1. 克隆仓库
git clone https://gitee.com/your-org/openkylin-contrib-helper.git
cd openkylin-contrib-helper

# 2. 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 3. 安装
pip install -e .
```

安装后可用 `okcontrib --help` 验证。

### 方式二：deb 包安装

```bash
sudo dpkg -i openkylin-contrib-helper_0.1.0-1_all.deb
```

安装后可全局使用 `okcontrib` 命令。

## Tab 自动补全

```bash
# 一次性生效（在项目根目录下）
source completions/okcontrib-completion.bash

# 永久生效 — 将下面这行加入 ~/.bashrc（注意替换实际项目路径）
echo 'source /path/to/openkylin-contrib-helper/completions/okcontrib-completion.bash' >> ~/.bashrc
```

补全效果：

| 输入 | 补全结果 |
|---|---|
| `okcontrib <TAB>` | auth, onboard, sig, issue, repo, stats, rank |
| `okcontrib sig <TAB>` | list, show |
| `okcontrib issue <TAB>` | list, recommend |
| `okcontrib issue -<TAB>` | -o, --owner, -r, --repo, -l, --labels |
| `okcontrib repo <TAB>` | fork, branch, pr |
| `okcontrib rank <TAB>` | top, compare, sig |

## 快速开始

```bash
# 1. 配置 Gitee Token（只需一次）
okcontrib auth <your_gitee_token>

# 2. 运行新手引导
okcontrib onboard
```

Token 和进度保存在 `~/.okcontrib/config.json`。

## 命令参考

### auth — 配置认证

```bash
okcontrib auth <your_gitee_token>
```

Token 获取地址：https://gitee.com/profile/personal_access_tokens

### onboard — 新手引导

```bash
okcontrib onboard
```

交互式 6 步引导：配置 Token → 选择 SIG → 推荐 Issue → Fork 仓库 → 创建分支 → PR 指引。

支持断点续传：退出后再次运行 `okcontrib onboard` 会从上次中断处继续。

### sig — 查看 SIG

```bash
# 列出所有 SIG
okcontrib sig list

# 查看指定 SIG 详情（负责人、维护仓库、快速开始命令）
okcontrib sig show UKUI
```

### issue — Issue 操作

```bash
# 推荐新手友好的 Issue（只搜索带「新手推荐」标签的）
okcontrib issue recommend

# 按仓库和标签筛选
okcontrib issue list -r community -l "新手推荐"
```

### repo — 仓库操作

```bash
# Fork 仓库
okcontrib repo fork -o openkylin -r community

# 在 Fork 后的仓库创建开发分支
okcontrib repo branch -o <your_gitee_id> -r community -n fix-issue-123

# 提交 Pull Request
okcontrib repo pr -o openkylin -r community \
  -t "fix: 修复 xxx 问题" \
  -b "详细描述修改内容" \
  --head fix-issue-123
```

### stats — 贡献统计

```bash
# 个人贡献总览（PR / Issue 汇总）
okcontrib stats overview

# 查看他人的统计
okcontrib stats overview -u <username>

# 最近 30 天活跃情况
okcontrib stats recent -d 30

# 查看待审核的 PR
okcontrib stats review
```

### rank — 社区排行

```bash
# 社区贡献排行榜 Top 20
okcontrib rank top

# 自定义排行数量
okcontrib rank top --top 10

# 与指定贡献者对比
okcontrib rank compare -t <username>

# 指定 SIG 维度排行
okcontrib rank sig -s UKUI
```

## 项目结构

```
src/
├── api/              # Gitee API 封装
│   └── gitee.py
├── commands/         # CLI 命令
│   ├── onboard.py    # 新手引导
│   ├── issue.py      # Issue 操作
│   ├── repo.py       # 仓库操作
│   ├── sig.py        # SIG 信息
│   ├── stats.py      # 贡献统计
│   └── leaderboard.py  # 排行对比
├── utils/            # 工具函数
│   ├── config.py     # 配置管理
│   └── check.py      # 规范检查
└── cli.py            # CLI 入口
completions/          # Shell 补全脚本
```

## 故障排查

| 现象 | 解决方法 |
|---|---|
| `okcontrib: command not found` | 确认已 `source .venv/bin/activate` 或已安装 deb 包 |
| `请先配置 Gitee Token` | 运行 `okcontrib auth <token>` |
| `无法获取 SIG 数据` | 检查网络连接，确认 Token 有效 |
| Python 版本错误 | 需要 Python ≥ 3.10，运行 `python3 --version` 确认 |
| 补全不生效 | 确认已 `source completions/okcontrib-completion.bash` |
| API 调用超时 | 网络问题，稍后重试；排行/统计命令需要扫描多个仓库，耐心等待 |

## License

MulanPSL-2.0
