Files
xhgitandClaude Code cf17c9ea42 Initial commit: 小南娘 - 面向可爱的蓝孩子的 git 学习实践项目
仿 Dress 的照片投稿仓库, 适配自建 Gitea 平台 git.xhmcl.com:
- README / GUIDE (PR 教程) / CONTRIBUTING / Q&A / EXIF / PARTIAL_CLONE (中英双语)
- A-Z + # 首字母目录结构
- .gitea: PR 模板、维护者名单、7 个纯 bash + API 的 Actions 工作流 (可选功能)

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-11-07 17:17:27 +08:00

244 lines
13 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 🌟 新手指南(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 模板**
- **请勿删除模板顶部的 `<!-- pr-type: images -->` 标记行**
- 在模板的「自查清单 / 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<br/>过期 PR 标记关闭"]
subgraph PRGRP["PR 触发类 pull_request_target"]
greetings["Greetings<br/>首次 PR 欢迎"]
check_pr_content["Check PR Content<br/>清单+类型+目录"]
check_file_size["Check File Size<br/>图片 ≤ 1 MiB"]
check_exif["Check EXIF<br/>敏感元数据检查"]
end
subgraph CMTGRP["评论触发类 issue_comment"]
auto_fix["Auto-fix<br/>/auto-fix 修复图片"]
fast_forward["Fast-forward<br/>/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<br/>首次贡献欢迎"]
prt --> content["Check PR Content"]
content --> c1{"自查清单<br/>全部勾选?"}
c1 -->|否| failc["评论 + 检查失败"]
c1 -->|是| c2{"pr-type 规则"}
c2 -->|"images 需有图片变更<br/>且目录归入 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 / 地址<br/>联系方式等敏感 EXIF?"}
e1 -->|否| pass
e1 -->|是| faile["评论敏感列表 + 失败"]
failc --> manual["作者手动修复并重新 push"]
manual --> prt
fails --> cmd["维护者或 PR 作者<br/>回复 /auto-fix"]
faile --> cmd
cmd --> af1["去除全部 EXIF"]
af1 --> af2{"压缩至 ≤ 1 MiB?"}
af2 -->|"成功"| af3["提交并 push 回 PR 分支"]
af2 -->|"20 次仍失败"| af4["整体回滚不 push<br/>评论提示手动修复"]
af3 --> prt
pass --> review["维护者审核"]
review --> ff["回复 /fast-forward<br/>变基合并 保留原始提交"]
ff --> done(["合并完成"])
prt -.->|"长期无活动"| stale["每日定时扫描<br/>标记 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 正文中的 `<!-- pr-type: xxx -->` 标签识别,取值为 `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` 会提示无法推送。