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

10 KiB
Raw Permalink Blame History

🌟 Beginner Guide (PR Tutorial)

Welcome to the XiaoNanNiang project! This guide will walk you through making your first Pull Request (PR).

This project is hosted on our self-hosted platform git.xhmcl.com, which is based on Gitea. The workflow is essentially the same as GitHub's, but button positions and some wording differ slightly; the steps below follow the Gitea UI.

Important: the platform only serves HTTP(S) — there is no SSH. Use https:// URLs for all clones and pushes; you don't need to configure any SSH keys.


📋 Workflow Overview

Fork the repository → Add your photos → Commit → Open a Pull Request (PR) → Wait for review & merge

Step 1: Fork the Repository

Fork = copy someone else's repository to your own account so you can modify it freely without affecting the original project!

  1. Open the XiaoNanNiang repository page
  2. Click the Fork button in the top-right corner
  3. This creates a copy under your account, at something like https://git.xhmcl.com/<your-username>/dress-pr

Step 2: Add Your Photos

Commit = a "snapshot" of your changes, recording what you modified. Each commit becomes a history entry!

Method A: Upload directly on the web (easiest, nothing to install)

  1. Go to your forked repository page (https://git.xhmcl.com/<your-username>/dress-pr)
  2. Pick the first-letter directory matching your planned folder name (e.g. Yueosa goes into Y; names starting with digits or symbols go into #)
  3. Click the + (add file) button in the top-right → New File
  4. In the file name field, enter your-folder-name/README.md (e.g. Yueosa/README.md) — this creates the folder automatically; the folder name does not have to match your account ID
  5. Write anything you like in the file (e.g. a self-introduction)
  6. Click Commit Changes
  7. Click + again → Upload File, and upload your photos into the folder you just created
  8. Click Commit Changes

Method B: Using the Git command line

Clone = download the remote repository to your computer. Push = upload your local commits to the remote repository (your fork).

# 1. Clone your fork (the platform only supports HTTP URLs)
# Use --depth 1 to fetch only the latest commit, since the repo history is large
git clone --depth 1 https://git.xhmcl.com/<your-username>/dress-pr.git
cd dress-pr

If the repository has too many images and a normal clone is too slow, you can use a partial clone instead to download only your own directory:

git clone --filter=blob:none --sparse --depth 1 https://git.xhmcl.com/<your-username>/dress-pr.git
cd dress-pr
git sparse-checkout set '<first-letter>/<your-folder-name>'

Partial clone does not affect normal commits and PRs. For directory management, full history and restoring the complete repository, read the Partial Clone Guide.

After cloning, create your folder and add photos:

# 2. Create your folder and add photos
# <first-letter> should match the first character of <your-folder-name>;
# use # for names starting with digits or symbols
mkdir -p <first-letter>/<your-folder-name>
cp /path/to/your/photos/* <first-letter>/<your-folder-name>/

# 3. Commit your changes
git add .
git commit -m "Add photos for <your-folder-name>"

# 4. Push to your fork
git push origin main

🔑 Authentication for push: the platform has no SSH, so Git will ask for a username and password when pushing. The password is not your login password — it's an "Access Token":

  1. Click your avatar in the top-right → Settings → Applications
  2. Under "Manage Access Tokens", click Generate Token
  3. Name it anything; grant repository read-write permissions (check the read/write boxes under repository if permissions are granular)
  4. Copy the token immediately after generation — it is shown only once
  5. When pushing: username = your account name, password = the token

Step 3: Open a Pull Request

Pull Request (PR) = an application to the maintainers of the original repository: "I made some changes in my fork, please merge them into the original project!"

  1. Go back to your forked repository page
  2. Click the Pull Requests tab → New Pull Request
    • If you just pushed, a banner usually appears on the page — just click its button
  3. Confirm the merge direction:
    • Base: the main branch of xhgit/dress-pr
    • Head: the branch you just pushed in your fork
  4. Fill in the PR description:
    • The platform auto-fills the repository's PR template
    • Do not delete the <!-- pr-type: images --> marker line at the top
    • Check every item in the "Checklist" section (change [ ] to [x])
    • Not submitting photos? Change pr-type to ci_wf / docs / others and follow the instructions in the template
  5. Click Create Pull Request

Step 4: Wait for Review

For photo PRs, the following items need to pass:

  • 📋 PR content: checklist complete and fully checked, image changes present, files under the matching A-Z/#/nickname/ directory
  • 📏 File size: images must be ≤ 1 MiB (1 MB)
  • 🔒 EXIF data: images must not contain high-sensitivity metadata (mainly GPS coordinates and address fields)

If the platform has Gitea Actions enabled, these checks run automatically, and results appear in the "Checks" area of the PR page; failures are explained in comments. If Actions is not enabled, maintainers perform these checks manually and will also explain problems in comments.

If a check fails, fix the problem and push again (or re-commit if using the web UI) — the checks re-run automatically.

If Actions is enabled, you can also comment /auto-fix to fix issues automatically: it compresses images to under 1 MiB and strips all EXIF (more thorough than the check). If you don't want your files modified, fix them yourself and push again.

Once a maintainer approves, your PR gets merged. Congratulations on your first open-source contribution! 🎉


⚠️ Before You Submit

  1. Compress images — make sure each image is under 1 MiB. Online tools like TinyPNG can help.
  2. Remove high-sensitivity EXIF — most importantly GPS coordinates, which can pinpoint exactly where the photo was taken. Photos may also carry address and contact information. See the EXIF field guide and the cleaning methods in Contribution Preparation.
  3. Name folders correctly — use meaningful folder names (they don't have to match your account ID) and place them under the matching A-Z/# directory by first character.
  4. Original photos only — submit only your own photos; stolen pictures are not accepted.
  5. Only modify your own folder — don't touch other people's folders or project files.
  6. Avoid Chinese characters and spaces in file names — they can cause display or download problems on some systems. Prefer English letters, digits and hyphens.
  7. Use a token for push, not your login password — see Step 2 Method B above.


Repository Workflows (Optional Feature)

⚠️ This section depends on the platform having Gitea Actions enabled with at least one Ubuntu runner. When not enabled, the automation below does not run and maintainers check manually. The workflow files live in .gitea/workflows/.

Workflow Overview

Workflow File Trigger Behavior
Greetings greetings.yml pull_request_target Posts a bilingual welcome comment on a contributor's first PR
Check PR Content check_pr_content.yml pull_request_target (opened / synchronize / reopened / edited) All PR types must have a fully checked checklist; images must include image changes under the A-Z/#/nickname/ structure; ci_wf changes must stay inside .gitea/; unknown pr-type fails
Check File Size check_file_size.yml pull_request_target (opened / synchronize / reopened) images PRs only: all changed images must be ≤ 1 MiB; oversized files are listed in a comment with a /auto-fix hint; check fails
Check Image EXIF Data check_exif.yml pull_request_target (opened / synchronize / reopened; concurrent runs cancelled) images PRs only: downloads changed images and runs exiftool to detect GPS / address / contact metadata; regular photography parameters are fine; hits are commented with a /auto-fix hint
Auto-fix Image Files auto_fix.yml issue_comment (comment starting with /auto-fix, by a maintainer or the PR author) Checks out the PR branch → strips all EXIF with exiftool → loops compression (jpegoptim / pngquant / optipng / ImageMagick, up to 20 attempts) down to ≤ 1 MiB → pushes back to the PR branch to re-trigger checks; on compression failure it reverts everything without pushing and comments the reason
Fast-forward for PR fast-forward.yml issue_comment / pull_request_review_comment (comment containing /fast-forward) Verifies the commenter has write access, then merges the PR via the platform API with rebase, preserving original commits and signatures; comments on failure
Mark Stale PRs stale.yml schedule (cron: 0 11 * * *) PRs only: long-inactive PRs are marked with a warning and closed after 7 more days without a response (issues are not touched)

Notes:

  • The pr-type is read from the <!-- pr-type: xxx --> tag in the PR body: images / ci_wf / docs / others; when missing it defaults to images.
  • All workflows are plain shell + platform API — no third-party actions, nothing fetched from GitHub.
  • If your Gitea version does not support the pull_request_target event, change it to pull_request in the workflow files.
  • /auto-fix needs to push back to the PR branch: configure the BOT_USER and BOT_TOKEN secrets in the repo's Settings → Actions → Secrets (a bot account token with write access to forks). Without them, /auto-fix comments an explanation and exits.