diff --git a/manual/fill-project-info/zh.md b/manual/fill-project-info/zh.md new file mode 100644 index 0000000..06007de --- /dev/null +++ b/manual/fill-project-info/zh.md @@ -0,0 +1,122 @@ +# 填写项目信息 + +该网站的数据源与界面展示相隔离,都存放在 `src/content` 文件夹中,每个子文件夹是个数据集,YAML 文件则是记录: + +| 文件夹 | 数据集 | 说明 | +| --- | --- | --- | +| `tag-types` | 标签类型 | 项目标签的几种类型,为标签分类时用,影响标签的优先顺序,几乎不需要改动 | +| `tags` | 标签 | 为项目分类时用,方便信息展示与按条件筛选,不太需要改动 | +| `contributors` | 贡献者/共建者 | 负责某生态项目的贡献者/共建者 | +| `projects` | 项目 | 已加入 OpenBuild 生态的项目 | + +上述几个数据集中,只有 `contributors` 和 `projects` 是频繁变动的。 + +## 通用规则 + +### 新增记录 + +在上述文件夹下创建一个以 `.yaml` 结尾的文件表明在数据集中新增一条记录,除了 `-` 不能使用其他符号,且它不能出现在开头,只能用作单词间的连接。 + +文件名中的英文字母只能用小写,当想要大写时,请考虑将其用小写写出,并在前面加上 `-` 进行连接(若非在名字的开头),如: + +``` +❌ OpenBuild +✅ openbuild +✅ open-build +``` + +### i18n + +有的字段(详见下方)得支持 i18n,需是如下结构: + +```yaml +en: 英语文本 +zh: 汉语文本 +``` + +英语是默认语言,因而在不(想)区分时把 `zh` 填写成与 `en` 相同。 + +## 数据集规则 + +### `tag-types` + +字段一览: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `id` | 字符串 | ✅ | 记录唯一标识符,小驼峰式命名 | +| `text` | i18n | ✅ | 显示文本 | + +该数据集实际起到的作用相当于枚举,只有 4 条记录,不能随意修改: + +- `category`——按照项目在应用中所起到的作用(或者说功能完整性)所划分的大类; +- `domain`——项目所主要从属的领域; +- `tech`——项目的主要技术栈; +- `general`——其他一些相对泛用的。 + +上述几条记录间存在优先级或范围大小顺序: + +``` +category > domain > tech > general +``` + +### `tags` + +字段一览: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `id` | 字符串 | ✅ | 记录唯一标识符,小驼峰式命名 | +| `text` | i18n | ✅ | 显示文本 | +| `type` | `tag-types` | ✅ | 归属于 `tag-types` 数据集的哪条记录 | + +这个数据集也是开放性较差的,只有当 `tag-types` 为 `tech` 或 `general` 时才可随意扩充,而值为 `category` 和 `domain` 时则又是「枚举」。 + +归属 `category` 的记录每个项目只能指定一个: + +- `app`——功能完整的应用或网站; +- `pluggable`——可插拔、可扩展的插件、服务; +- `semi-finished`——作为底层依赖的框架、库。 + +归属 `domain` 的记录每个项目可以指定多个,但最好只指定一个最具特色的: + +- `web3`——面向 Web3 的; +- `frontend`——同时面向 Web2、Web3 且以前端为主的; +- `backend`——同时面向 Web2、Web3 且以后端为主的。 + +### `contributors` + +字段一览: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `nickname` | i18n | ✅ | 常用的昵称/网名/花名 | +| `github` | 对象(见下) | ✅ | GitHub 账号信息 | + +字段 `github` 的结构为: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `id` | 数字 | ✅ | GitHub 用户 ID,通过复制 GitHub 个人头像 URL 取得:`https://avatars.githubusercontent.com/u/:id` | +| `username` | 字符串 | ✅ | GitHub 用户名,即个人主页 URL 中末尾部分:`https://github.com/:username` | + +### `projects` + +字段一览: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `id` | 字符串 | ✅ | 记录唯一标识符,小驼峰式命名 | +| `title` | i18n | ✅ | 项目名称 | +| `description` | i18n | ✅ | 项目简介 | +| `owners` | 数组 | ✅ | 项目负责人(主要维护者),GitHub 用户名数组,按主次顺序排序 | +| `repo` | 网址或对象(见下) | ❌ | 项目在 GitHub 上的仓库信息或组织网址 | +| `homepage` | 网址 | ❌ | 项目官网 | +| `tags` | 数组 | ❌ | 项目标签,数据集 `tags` 的 `id` 字段数组,规则参照数据集 `tag-types` 与 `tags` 的相关说明 | + +关于字段 `repo`,若该项目实际由多个 GitHub 仓库构成,填写相应 GitHub 组织网址,否则填写 GitHub 仓库信息,结构如下: + +| 字段名 | 值数据类型 | 必需 | 说明 | +| --- | --- | --- | --- | +| `owner` | 字符串 | ✅ | GitHub 仓库拥有者,即组织名或用户名 | +| `name` | 字符串 | ✅ | GitHub 仓库名 |