# 🌟 新手指南(PR 教程)
欢迎来到小南娘项目!这份指南将帮助你完成第一次合并请求(Pull Request,简称 PR)。
> 本项目托管在自建平台 [git.xhmcl.com](https://git.xhmcl.com),基于 Gitea。流程和 GitHub 基本相同,但按钮位置和个别叫法略有差异,下文按 Gitea 的界面来写。
>
> **重要:本平台只开放 HTTP(S),没有 SSH。** 所有克隆和推送都使用 `https://` 地址,你不需要配置任何 SSH Key。
---
## 📋 提交流程概览
```
Fork(复刻)仓库 → 添加你的照片 → 提交 Commit → 发起合并请求(PR)→ 等待审核合并
```
---
## 第一步:Fork 仓库
> **Fork(复刻)** = 把别人的仓库「复制」一份到你自己的账号下,让你可以自由修改喵,不会影响原项目喵!
1. 打开 [小南娘仓库页面](https://git.xhmcl.com/xhgit/dress-pr)
2. 点击页面右上角的 **Fork(复刻)** 按钮
3. 这会在你的账号下创建一份仓库副本,地址类似 `https://git.xhmcl.com/<你的用户名>/dress-pr`
---
## 第二步:添加你的照片
> **Commit** = 给你的修改拍一张「快照」,记录你改了什么内容,每次 Commit 都会生成一条历史记录喵!
### 方法 A:直接在网页上传(最简单,不需要安装任何东西)
1. 进入你 Fork 后的仓库页面(`https://git.xhmcl.com/<你的用户名>/dress-pr`)
2. 根据计划使用的个人文件夹名称选择对应的首字母目录(如 `Yueosa` 进入 `Y`,数字或符号开头则进入 `#`)
3. 点击右上角的 **+**(添加文件)→ **新建文件(New File)**
4. 在文件名栏输入 `你的文件夹名/README.md`(如 `Yueosa/README.md`),这会自动创建文件夹;文件夹名无需与你的账号 ID 相同
5. 在文件中随意写一些内容(如自我介绍)
6. 点击 **提交更改(Commit Changes)**
7. 再次点击 **+** → **上传文件(Upload File)**,将你的照片上传到刚创建的文件夹中
8. 点击 **提交更改(Commit Changes)**
### 方法 B:使用 Git 命令行
> **Clone** = 把远程仓库下载到本地电脑。
> **Push** = 把本地的 Commit 上传同步到远程仓库(你的 Fork)。
```bash
# 1. 克隆你 Fork 的仓库(本平台只支持 HTTP 地址)
# 由于仓库 commit 历史较多,使用 --depth 1 仅拉取最近一次提交
git clone --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr
```
如果你觉得仓库图片较多、普通克隆太慢,可以使用部分克隆代替上面的命令,只下载自己的目录:
```bash
git clone --filter=blob:none --sparse --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr
git sparse-checkout set '<首字母>/<你的文件夹名>'
```
部分克隆不会影响正常提交和 PR。目录管理、完整历史和恢复完整仓库的方法请阅读[部分克隆指南](PARTIAL_CLONE.md)。
克隆完成后,创建你的文件夹并添加照片:
```bash
# 2. 创建你的文件夹并添加照片
# <首字母> 应与 <你的文件夹名> 的首字符对应;数字或符号开头时使用 #
mkdir -p <首字母>/<你的文件夹名>
cp /path/to/your/photos/* <首字母>/<你的文件夹名>/
# 3. 提交更改
git add .
git commit -m "Add photos for <你的文件夹名>"
# 4. 推送到你的 Fork
git push origin main
```
> 🔑 **推送时需要认证**:本平台没有 SSH,推送时 Git 会要求输入用户名和密码。密码**不是你的登录密码**,而是「访问令牌(Access Token)」:
>
> 1. 点击右上角头像 → **设置(Settings)** → **应用(Applications)**
> 2. 在「管理访问令牌 / Access Tokens」一栏点击 **生成令牌(Generate Token)**
> 3. 令牌名称随意填写;权限勾选仓库读写(Repository: read-write,若平台按细粒度列出,勾选 `repository` 下的读写权限)
> 4. 生成后**立即复制保存**,它只会显示这一次
> 5. 推送时:用户名填你的账号名,密码粘贴这个令牌
---
## 第三步:发起合并请求(Pull Request)
> **合并请求(Pull Request,PR)** = 向原仓库的维护者提出申请:「我在我的 Fork 里做了一些修改,请把它们合并到原项目里吧喵!」
1. 回到你 Fork 的仓库页面
2. 点击 **合并请求(Pull Requests)** 标签 → **新建合并请求(New Pull Request)**
- 如果刚推送完,页面上通常会出现一条提示横幅,直接点上面的按钮即可
3. 确认合并方向:
- **目标(base)**:`xhgit/dress-pr` 的 `main` 分支
- **源(head)**:你的 Fork 仓库里你刚推送的分支
4. 填写 PR 描述:
- 平台会自动填入仓库提供的 **PR 模板**
- **请勿删除模板顶部的 `` 标记行**
- 在模板的「自查清单 / Checklist」中**逐项勾选**(把 `[ ]` 改成 `[x]`)
- 本次不是交照片?把 `pr-type` 改为 `ci_wf` / `docs` / `others`,并按提示勾选清单
5. 点击 **创建合并请求(Create Pull Request)**
---
## 第四步:等待审核
提交照片类 PR 后,需要检查以下事项:
- 📋 **PR 内容**:自查清单是否齐全并全部勾选、是否包含图片变更、文件是否位于对应的 `A-Z/#/昵称/` 目录下
- 📏 **文件大小**:图片是否在 1 MiB(1 MB)以内
- 🔒 **EXIF 信息**:图片是否包含高敏感元数据(主要是 **GPS 坐标**及地址类字段)
> 如果平台启用了 Gitea Actions,以上检查会**自动运行**,检查结果直接显示在 PR 页面的「检查 / Checks」区域;未通过时 PR 下会留下评论说明原因。
> 如果平台暂未启用 Actions,则由维护者人工检查,同样会在评论里说明原因。
检查未通过时,按提示修改后重新 **push**(网页上传则重新提交),检查会自动重跑。
如果平台启用了 Actions,还可以在评论区发送 **`/auto-fix`** 命令自动处理:将图片压缩到 1 MiB 以内,并去除**全部** EXIF(比检查更彻底)。若你不希望文件被改动,请自行处理好后再推送。
维护者审核通过后,你的 PR 就会被合并。恭喜你完成了一次开源贡献!🎉
---
## ⚠️ 提交前请注意
1. **压缩图片** — 确保每张图片小于 1 MiB。可以使用 [TinyPNG](https://tinypng.com/) 等在线工具压缩。
2. **移除高敏感 EXIF 信息** — 最重要的是删除 **GPS 坐标**,它能精确暴露你的拍摄地点。照片还可能携带地址、联系方式等信息。详见 [EXIF 字段说明](EXIF.md) 和 [贡献准备中的清理方法](CONTRIBUTING.md)。
3. **正确命名文件夹** — 使用有意义的文件夹名(无需与账号 ID 相同),并按其首字符放在对应的 `A-Z/#` 目录下。
4. **原创图片** — 只提交你自己的照片,不接受盗图。
5. **只修改自己的文件夹** — 请不要改动他人的文件夹或其他项目文件,避免给维护者带来不必要的麻烦。
6. **文件名避免中文和空格** — 文件名中的中文字符或空格可能导致部分系统无法正常显示或下载,请尽量使用英文字母、数字和连字符。
7. **推送用令牌,不用登录密码** — 命令行推送时密码位置填访问令牌(见第二步方法 B 的说明)。
---
## 🔗 参考链接
- [项目说明](README.md)
- [贡献准备](CONTRIBUTING.md)
- [EXIF 说明](EXIF.md)
- [Q&A](Q&A.md)
- [部分克隆指南](PARTIAL_CLONE.md)
- [已合并的 PR 参考](https://git.xhmcl.com/xhgit/dress-pr/pulls?state=closed)
---
# 仓库 Workflow 流程(可选功能)
> ⚠️ 本节内容依赖平台启用 **Gitea Actions** 并注册至少一个 Ubuntu runner。当前未启用时,以下自动化不运行,检查由维护者人工完成。工作流文件位于 [.gitea/workflows/](.gitea/workflows/)。
## 一、工作流体系总览
```mermaid
flowchart TD
ev1(["PR 开启 / 更新 / 重开 / 编辑"]) --> PRGRP
ev2(["PR 评论含指令"]) --> CMTGRP
ev3(["定时任务 每日 11:00 UTC"]) --> stale["Mark Stale
过期 PR 标记关闭"]
subgraph PRGRP["PR 触发类 pull_request_target"]
greetings["Greetings
首次 PR 欢迎"]
check_pr_content["Check PR Content
清单+类型+目录"]
check_file_size["Check File Size
图片 ≤ 1 MiB"]
check_exif["Check EXIF
敏感元数据检查"]
end
subgraph CMTGRP["评论触发类 issue_comment"]
auto_fix["Auto-fix
/auto-fix 修复图片"]
fast_forward["Fast-forward
/fast-forward 合并"]
end
check_file_size -->|"评论提示"| auto_fix
check_exif -->|"评论提示"| auto_fix
auto_fix -.->|"push 后重跑"| check_file_size
auto_fix -.->|"push 后重跑"| check_exif
```
## 二、图片 PR 完整生命周期
```mermaid
flowchart TD
start(["贡献者提交 PR"]) --> prt["pull_request_target 触发"]
prt --> greet["Greetings
首次贡献欢迎"]
prt --> content["Check PR Content"]
content --> c1{"自查清单
全部勾选?"}
c1 -->|否| failc["评论 + 检查失败"]
c1 -->|是| c2{"pr-type 规则"}
c2 -->|"images 需有图片变更
且目录归入 A-Z/#/昵称"| pass["检查通过"]
c2 -->|"ci_wf 变更限 .gitea/"| pass
c2 -->|"docs/others 仅查清单"| pass
c2 -->|不符合| failc
prt --> size["Check File Size"]
size --> s1{"图片均 ≤ 1 MiB?"}
s1 -->|是| pass
s1 -->|否| fails["评论超限列表 + 失败"]
prt --> exif["Check EXIF"]
exif --> e1{"含 GPS / 地址
联系方式等敏感 EXIF?"}
e1 -->|否| pass
e1 -->|是| faile["评论敏感列表 + 失败"]
failc --> manual["作者手动修复并重新 push"]
manual --> prt
fails --> cmd["维护者或 PR 作者
回复 /auto-fix"]
faile --> cmd
cmd --> af1["去除全部 EXIF"]
af1 --> af2{"压缩至 ≤ 1 MiB?"}
af2 -->|"成功"| af3["提交并 push 回 PR 分支"]
af2 -->|"20 次仍失败"| af4["整体回滚不 push
评论提示手动修复"]
af3 --> prt
pass --> review["维护者审核"]
review --> ff["回复 /fast-forward
变基合并 保留原始提交"]
ff --> done(["合并完成"])
prt -.->|"长期无活动"| stale["每日定时扫描
标记 stale 7 天未回应则关闭"]
```
## 三、工作流一览
| 工作流 | 文件 | 触发方式 | 主要行为 |
| --- | --- | --- | --- |
| Greetings | `greetings.yml` | `pull_request_target` | 对首次贡献者的 PR 发送中英双语欢迎评论 |
| Check PR Content | `check_pr_content.yml` | `pull_request_target`(opened / synchronize / reopened / edited) | 所有类型 PR 须勾选自查清单;`images` 须有图片变更且目录符合 `A-Z/#/昵称/` 结构;`ci_wf` 变更须全部在 `.gitea/` 内;未识别的 `pr-type` 报错 |
| Check File Size | `check_file_size.yml` | `pull_request_target`(opened / synchronize / reopened) | 仅 `images` 类 PR:变更图片须全部 ≤ 1 MiB,超限则评论列出文件并提示 `/auto-fix`,检查失败 |
| Check Image EXIF Data | `check_exif.yml` | `pull_request_target`(opened / synchronize / reopened,同 PR 并发取消) | 仅 `images` 类 PR:下载变更图片,用 `exiftool` 检查 GPS、地址、联系方式等高敏感 EXIF;普通摄影参数不拦截;命中则评论并提示 `/auto-fix` |
| Auto-fix Image Files | `auto_fix.yml` | `issue_comment`(评论以 `/auto-fix` 开头,且为维护者或 PR 作者) | 检出 PR 分支 → `exiftool` 清除全部 EXIF → 循环压缩(`jpegoptim / pngquant / optipng / ImageMagick`,最多 20 次)至 ≤ 1 MiB → push 回 PR 分支触发检查重跑;压缩失败则整体回滚不 push 并评论说明 |
| Fast-forward for PR | `fast-forward.yml` | `issue_comment` / `pull_request_review_comment`(评论含 `/fast-forward`) | 校验评论者有 `write` 权限后调用平台 API 以变基(rebase)方式合并 PR,保留原始提交与签名;合并失败时评论说明原因 |
| Mark Stale Issues and PRs | `stale.yml` | `schedule`(cron: `0 11 * * *`) | 仅针对 PR:长期无活动先标记并提醒 7 天内回应,仍无回应则关闭(issue 不处理) |
> **说明**:
> - pr-type 通过 PR 正文中的 `` 标签识别,取值为 `images / ci_wf / docs / others`,缺省按 `images` 处理。
> - 所有工作流均为纯 shell + 平台 API 实现,不依赖任何第三方 action,无需从 GitHub 拉取任何内容。
> - 若你的 Gitea 版本不支持 `pull_request_target` 事件,请把工作流里的 `pull_request_target` 改为 `pull_request`。
> - `/auto-fix` 需要把图片 push 回 PR 分支,请预先在仓库「设置 → Actions → Secrets」中配置 `BOT_USER` 与 `BOT_TOKEN`(一个有 Fork 仓库写权限的账号令牌)。未配置时 `/auto-fix` 会提示无法推送。