仿 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>
174 lines
10 KiB
Markdown
174 lines
10 KiB
Markdown
# 🌟 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.
|