Files
dress-pr/GUIDE.md
T
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

13 KiB
Raw Blame History

🌟 新手指南(PR 教程)

欢迎来到小南娘项目!这份指南将帮助你完成第一次合并请求(Pull Request,简称 PR)。

本项目托管在自建平台 git.xhmcl.com,基于 Gitea。流程和 GitHub 基本相同,但按钮位置和个别叫法略有差异,下文按 Gitea 的界面来写。

重要:本平台只开放 HTTP(S),没有 SSH。 所有克隆和推送都使用 https:// 地址,你不需要配置任何 SSH Key。


📋 提交流程概览

Fork(复刻)仓库 → 添加你的照片 → 提交 Commit → 发起合并请求(PR)→ 等待审核合并

第一步:Fork 仓库

Fork(复刻) = 把别人的仓库「复制」一份到你自己的账号下,让你可以自由修改喵,不会影响原项目喵!

  1. 打开 小南娘仓库页面
  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)。

# 1. 克隆你 Fork 的仓库(本平台只支持 HTTP 地址)
# 由于仓库 commit 历史较多,使用 --depth 1 仅拉取最近一次提交
git clone --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr

如果你觉得仓库图片较多、普通克隆太慢,可以使用部分克隆代替上面的命令,只下载自己的目录:

git clone --filter=blob:none --sparse --depth 1 https://git.xhmcl.com/<你的用户名>/dress-pr.git
cd dress-pr
git sparse-checkout set '<首字母>/<你的文件夹名>'

部分克隆不会影响正常提交和 PR。目录管理、完整历史和恢复完整仓库的方法请阅读部分克隆指南。

克隆完成后,创建你的文件夹并添加照片:

# 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 等在线工具压缩。
  2. 移除高敏感 EXIF 信息 — 最重要的是删除 GPS 坐标,它能精确暴露你的拍摄地点。照片还可能携带地址、联系方式等信息。详见 EXIF 字段说明 和 贡献准备中的清理方法。
  3. 正确命名文件夹 — 使用有意义的文件夹名(无需与账号 ID 相同),并按其首字符放在对应的 A-Z/# 目录下。
  4. 原创图片 — 只提交你自己的照片,不接受盗图。
  5. 只修改自己的文件夹 — 请不要改动他人的文件夹或其他项目文件,避免给维护者带来不必要的麻烦。
  6. 文件名避免中文和空格 — 文件名中的中文字符或空格可能导致部分系统无法正常显示或下载,请尽量使用英文字母、数字和连字符。
  7. 推送用令牌,不用登录密码 — 命令行推送时密码位置填访问令牌(见第二步方法 B 的说明)。

🔗 参考链接


仓库 Workflow 流程(可选功能)

⚠️ 本节内容依赖平台启用 Gitea Actions 并注册至少一个 Ubuntu runner。当前未启用时,以下自动化不运行,检查由维护者人工完成。工作流文件位于 .gitea/workflows/。

一、工作流体系总览

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 完整生命周期

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 会提示无法推送。