shumengya
1975e51960
- README.md: 仓库门面，含特性、API 文档、快速开始、部署、目录结构、协议 - LICENSE: MIT，约束代码 - ASSET_LICENSE.md: CC BY-NC-SA 4.0，约束表情包素材 - CONTRIBUTING.md: 投稿流程、commit 与分支规范、PR 自检清单 - CHANGELOG.md: Keep a Changelog 格式，1.0.0 首发条目 - .gitignore: 补充 macOS/Windows/IDE/Python/日志等忽略项 - .github/ISSUE_TEMPLATE/: bug / feature / question 三个模板 - .github/PULL_REQUEST_TEMPLATE.md: 含素材来源声明与自检清单
233 lines
7.1 KiB
Markdown
233 lines
7.1 KiB
Markdown
# 投稿指南 🤝
|
||
|
||
非常欢迎你一起完善这个表情包图库！这份文档说明**怎么提交素材 / 修复 / 功能**才能又快又稳被合入。
|
||
|
||
> 阅读前请先看一眼 [README](./README.md) 和 [ASSET_LICENSE](./ASSET_LICENSE.md)，了解项目结构与协议。
|
||
|
||
## 目录
|
||
|
||
- [我能贡献什么？](#-我能贡献什么)
|
||
- [我该 fork 哪个分支？](#-我该-fork-哪个分支)
|
||
- [提 Issue](#-提-issue)
|
||
- [素材投稿流程](#-素材投稿流程)
|
||
- [代码 / 文档投稿](#-代码--文档投稿)
|
||
- [约定与规范](#-约定与规范)
|
||
- [本地自检](#-本地自检)
|
||
- [PR 流程](#-pr-流程)
|
||
- [审核标准](#-审核标准)
|
||
- [行为准则](#-行为准则)
|
||
|
||
## 🎁 我能贡献什么？
|
||
|
||
| 类型 | 说明 |
|
||
| --- | --- |
|
||
| 🖼 新表情 / 新分类 | 投到 `public/meme/<新分类>/` 下 |
|
||
| 🐛 修坏图 / 错图 | 替换、删除或重新分类 |
|
||
| 🌐 图库前端改进 | 修改 `public/index.html`（单文件，无构建） |
|
||
| ⚙️ 构建脚本改进 | 改 `scripts/generate-manifest.mjs` 或 `转化.py` |
|
||
| 📝 文档 | 改进 `README.md`、本文件、API 说明页 |
|
||
| 🧪 Bug 报告 / 体验建议 | 提 Issue |
|
||
|
||
## 🌿 我该 fork 哪个分支？
|
||
|
||
**默认 `main` 分支。** 任何 PR 都基于 `main`。
|
||
|
||
预览分支 `preview` 是 wrangler 部署的临时产物，**不要**直接 PR 到那里。
|
||
|
||
## 🐞 提 Issue
|
||
|
||
- **Bug 报告**：用 [Bug 报告模板](.github/ISSUE_TEMPLATE/bug_report.md)，按字段填好
|
||
- **新功能 / 改进建议**：用 [功能建议模板](.github/ISSUE_TEMPLATE/feature_request.md)
|
||
- **侵权 / 删除请求**：标题加 `[takedown]`，并附素材路径和说明
|
||
|
||
## 🖼 素材投稿流程
|
||
|
||
### 0. 先确认你有分发权
|
||
|
||
只投**以下任一**的素材：
|
||
|
||
- ✅ 你自己原创 / 自己画的表情包
|
||
- ✅ 协议允许二次分发的素材（如 CC BY、CC BY-SA、公共领域）
|
||
- ✅ 你已经获得作者明确授权
|
||
|
||
**别投**：商用素材、明显盗图、官方美术资源（除非协议明确允许）。
|
||
|
||
### 1. 处理素材（推荐）
|
||
|
||
> `转化.py` 会帮你自动编号、缩放、转格式；**不要**手动起 `1.webp` 这样的名字，编号是脚本加的。
|
||
|
||
```bash
|
||
# 拿一个新分类举例
|
||
mkdir -p 原图/我的新分类
|
||
cp ~/Downloads/表情.png 原图/我的新分类/
|
||
|
||
# 装 Pillow（一次性）
|
||
python -m pip install pillow
|
||
|
||
# 转换：自动编号、统一 webp/gif、最长边缩放到 250px
|
||
python 转化.py
|
||
|
||
# 把生成结果拷入发布目录
|
||
cp -r 原图-已处理/我的新分类 public/meme/
|
||
```
|
||
|
||
参数说明：
|
||
|
||
| 参数 | 作用 |
|
||
| --- | --- |
|
||
| `--delete-sources` | 处理完删除 `原图/` 里的源文件（默认保留） |
|
||
| `--max-side 250` | 最长边像素，默认 250px |
|
||
| `--jobs 10` | 并行线程数 |
|
||
|
||
### 2. 直接投到 `public/meme/`
|
||
|
||
如果你的素材**已经**是 `N.webp` / `N.gif` 命名，且最长边 ≤ 250px，可以**直接**放到 `public/meme/<分类>/`，不跑 `转化.py`。脚本在生成清单时会自动识别已编号的素材。
|
||
|
||
### 3. 重新生成清单
|
||
|
||
```bash
|
||
npm run build
|
||
```
|
||
|
||
这一步会重写 `public/memes.json` 与 `dist/memes.json`，**请把这两个文件一起 commit**。
|
||
|
||
### 4. 提交 PR
|
||
|
||
- **PR 标题**：`feat(meme): 新增 xxx 分类` 或 `fix(meme): 删除损坏的 白色小人/123.webp`
|
||
- **PR 描述**：
|
||
- 素材来源（自己画 / 转载自 xxx / 协议 xxxx）
|
||
- 大致数量和分类
|
||
- 截图（可选）
|
||
|
||
## 💻 代码 / 文档投稿
|
||
|
||
### 前端
|
||
|
||
- `public/index.html` 是**单文件**前端（HTML + 内联 CSS + 内联 JS，**无任何依赖**）
|
||
- 改完**直接刷新本地预览**就能看效果：
|
||
```bash
|
||
npm run dev
|
||
# 浏览器打开 http://localhost:8788
|
||
```
|
||
- 尽量保持：
|
||
- 移动端优先 → 桌面端
|
||
- 暗色模式自适应
|
||
- 键盘可达（`Tab`、`Enter`、`Esc`）
|
||
- 不引入外部依赖
|
||
|
||
### 构建脚本
|
||
|
||
- `scripts/generate-manifest.mjs` — Node 18+ ESM
|
||
- `转化.py` — Python 3.8+，只依赖 Pillow
|
||
- 改完跑 `npm run build` 验证 `memes.json` 生成正确
|
||
|
||
### 文档
|
||
|
||
- 写完后检查一下渲染效果：本地打开 `README.md` 看看排版
|
||
- 文档用 **中文**；变量名、函数名、commit 标题用**英文**
|
||
- 引用外部链接优先官方文档
|
||
|
||
## 📐 约定与规范
|
||
|
||
### Commit 消息
|
||
|
||
遵循 [Conventional Commits](https://www.conventionalcommits.org/)：
|
||
|
||
```
|
||
feat(meme): 新增 黄仁勋 分类
|
||
fix(meme): 替换损坏的 滑稽/3.webp
|
||
docs: 完善 README 的 API 文档
|
||
style(frontend): 调整移动端栅格断点
|
||
refactor(scripts): 拆分 generate-manifest.mjs
|
||
chore: 升级 wrangler 到 4.7
|
||
```
|
||
|
||
允许类型：`feat` / `fix` / `docs` / `style` / `refactor` / `perf` / `test` / `chore` / `ci`
|
||
|
||
### 分支名
|
||
|
||
- `feat/<短描述>`：新功能 / 新分类
|
||
- `fix/<短描述>`：修 bug
|
||
- `docs/<短描述>`：文档
|
||
- `chore/<短描述>`：杂项
|
||
|
||
例：`feat/meme-add-minecraft-pack`、`fix/meme-broken-gifs`
|
||
|
||
### 分类目录命名
|
||
|
||
- 用**清晰的中文**，避免过长的字串
|
||
- 不要带空格（用空格的话在 URL 里得编码，体验差）
|
||
- 不要带特殊符号 `/`、`\`、`#`、`?`
|
||
- 想拆同主题的子分类就再加一个目录，例如 `抹茶旦旦2`
|
||
|
||
### 素材命名
|
||
|
||
- **不要**自己命名；让 `转化.py` 续号
|
||
- 已经手动起好的也 OK（`1.webp` / `2.gif` 这种），脚本会从已有最大编号续起
|
||
|
||
### 文件格式
|
||
|
||
- 静态图：`.webp`（默认 lossless，质量 + 体积兼顾）
|
||
- 动图：`.gif`（Pillow 转码；WebP 动图也会被转成 GIF 提升兼容性）
|
||
- 缩放：最长边 **250px**
|
||
- 单张建议 ≤ **30KB**；动图 ≤ **100KB**
|
||
|
||
## ✅ 本地自检
|
||
|
||
提交前请跑一遍：
|
||
|
||
```bash
|
||
# 1. 构建通过、清单生成正常
|
||
npm run build
|
||
|
||
# 2. 本地预览，检查图库显示、复制/下载、侧边栏等
|
||
npm run dev
|
||
|
||
# 3. （可选）检查素材大小
|
||
du -sh public/meme/<新分类>/
|
||
ls -la public/meme/<新分类>/ | head
|
||
```
|
||
|
||
确认：
|
||
|
||
- [ ] 新分类在侧边栏出现，编号连续无跳号
|
||
- [ ] 点开任意一张能正常复制 URL / Markdown / HTML / 下载
|
||
- [ ] 移动端（DevTools 切到 375px）布局没崩
|
||
- [ ] 没有把 `dist/`、`node_modules/`、`__pycache__/`、`*.pyc` 等 commit 进去
|
||
|
||
## 🔁 PR 流程
|
||
|
||
1. Fork → 新分支 → 改代码 / 投素材
|
||
2. `npm run build` 自检
|
||
3. 提 PR 到 `main`
|
||
4. 描述清楚改了什么；附截图（如有 UI 变化）
|
||
5. 等 CI / 维护者 review
|
||
6. 必要的话按 review 改一轮
|
||
7. 合并后 Cloudflare Pages 会自动部署
|
||
|
||
## 🧐 审核标准
|
||
|
||
PR 被合的优先级：
|
||
|
||
- ✅ 修复真实 bug
|
||
- ✅ 引入来源清晰的新素材
|
||
- ✅ 改进图库体验（无障碍 / 性能 / 暗色）
|
||
- ✅ 改进文档可读性
|
||
- ⚠️ 大批量素材（> 200 张）建议先开 Issue 沟通
|
||
- ❌ 协议不清晰的素材
|
||
- ❌ 引入外部依赖（CDN 库、构建工具）的"重"改动
|
||
- ❌ 与项目无关的"小改"（拼写错误除外）
|
||
|
||
## 🫶 行为准则
|
||
|
||
- 友善、尊重、就事论事
|
||
- 拒绝任何形式的骚扰、歧视、人身攻击
|
||
- 提 Issue / 评论前先搜一下避免重复
|
||
- 不确定时先问，错了就改
|
||
|
||
违反行为准则的评论 / PR 会被关闭，屡次违反会被封禁。
|
||
|
||
---
|
||
|
||
有任何问题，欢迎在 [Issue](https://github.com/shumengya/meme-api/issues) 里沟通。谢谢你的贡献！🌱
|