# 🌟 新手指南(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` 会提示无法推送。