Files
dress-pr/en-US/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

174 lines
10 KiB
Markdown
Raw 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.
# 🌟 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](https://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](https://git.xhmcl.com/xhgit/dress-pr)
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).
```bash
# 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:
```bash
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](PARTIAL_CLONE.md).
After cloning, create your folder and add photos:
```bash
# 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](https://tinypng.com/) 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](EXIF.md) and the [cleaning methods in Contribution Preparation](CONTRIBUTING.md).
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.
---
## 🔗 Reference Links
- [Project README](README.md)
- [Contribution Preparation](CONTRIBUTING.md)
- [EXIF Guide](EXIF.md)
- [Q&A](Q&A.md)
- [Partial Clone Guide](PARTIAL_CLONE.md)
- [Merged PR examples](https://git.xhmcl.com/xhgit/dress-pr/pulls?state=closed)
---
# 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/](../.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.