# 🌟 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//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//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//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//dress-pr.git cd dress-pr git sparse-checkout set '/' ``` 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 # should match the first character of ; # use # for names starting with digits or symbols mkdir -p / cp /path/to/your/photos/* // # 3. Commit your changes git add . git commit -m "Add photos for " # 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 `` 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 `` 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.