Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
105 lines (70 loc) · 5.02 KB

CONTRIBUTING.md

File metadata and controls

105 lines (70 loc) · 5.02 KB
Raw

贡献指南

感谢参与完善 CQUT-OSP 的视觉语言与品牌规范。

规范来自并服务于真实项目，不为形式上的完整。

项目结构

本仓库为 pnpm monorepo，包含以下内容：

路径 说明
apps/docs VitePress 规范网站（中文为根，en/ 为英文）
assets/logo/source 标志 SVG 源文件（唯一来源）
assets/templates/source 模板 SVG 源文件
tests/ Vitest 单元测试（资产与对比度）
apps/docs/.vitepress/theme 站点主题样式与自定义组件
apps/docs/.vitepress/config.mts 站点配置（导航、侧边栏、多语言）

assets/*/export 与站点下载目录（apps/docs/public/downloads）均由脚本构建生成，严禁直接编辑。

快速开始

需要 Node.js 24 及仓库指定的 pnpm 版本（见 package.json）。安装依赖后：

pnpm install
pnpm dev          # 生成资产并启动规范站点（端口 4322）

开发流程

  1. 基于 package.json 指定的 Node.js 与 pnpm 版本安装依赖；拉取远程更新后先运行 pnpm install。
  2. 运行 pnpm dev 浏览规范网站。
  3. 修改源文件；assets/*/source 变更后运行 pnpm assets:build 重新生成导出物。
  4. 同步更新英文页面与 CHANGELOG.md（见下文「多语言」「变更记录」）。
  5. 提交前运行 pnpm verify，该命令一次性校验格式、类型、测试与构建。

贡献内容

规范文档

规范页面存放于 apps/docs/：中文页面为根目录（如 brand/logo.md），英文对应页面在 en/（如 en/brand/logo.md）。

  • 新增或修改页面时，两门语言均需同步，并保持结构、标题与链接一一对应。
  • 中文采用页面根路径链接；英文页面内部链接使用 /en/ 前缀。
  • 页面加入导航或侧边栏：编辑 apps/docs/.vitepress/config.mts，分别在中文根配置与 locales.en 下补充条目。
  • 多语言实现细节见 VitePress i18n。

站点样式与组件

颜色、间距与主题样式集中维护于 apps/docs/.vitepress/theme/custom.css，变更需同时检查亮暗主题。

自定义组件位于 apps/docs/.vitepress/theme/components/。组件内文案需按 useData().lang 提供中英文，禁止硬编码单一语言。

品牌资产

  • 修改 Logo 图案：编辑 assets/logo/source/*.svg（Logo 与方形标志分别匹配 viewBox="0 0 512 128" 与 128 128），运行 pnpm assets:build。
  • 修改模板：编辑 assets/templates/source/*.svg，再重新生成。
  • 生成的 PNG、下载目录副本与 manifest.json 由 scripts/build-assets.mjs 输出，不要手动改动。

测试与 CI

  • 单元测试位于 tests/*.test.ts，vp test 运行（资产一致性、对比度达标等）。
  • CI（.github/workflows/ci.yml）在每次推送时执行 pnpm verify，通过后自动构建并部署到 GitHub Pages。
  • 本地可运行 pnpm check（格式/类型/静态检查）与 pnpm test。

设计变更要求

Logo、主色、品牌名称和授权范围属于高影响变更。提案必须说明动机、受影响产品、迁移方式，并提供小尺寸、单色、亮暗背景和键盘/对比度验证。

颜色、间距和主题样式应集中维护，并说明至少一个真实使用场景；组件特有的样式值保留在对应组件内部。

新增或修改用途时，同步更新 README.md 许可表与相关文档页。

提交信息

提交信息使用 emoji 前缀、中文编写、保持简洁，按变更类型选择：

变更类型 Emoji
新功能 (feat) ✨
修复 (fix) 🐛
文档 (docs) 📝
样式 (style) 💄
重构 (refactor) ♻️
性能 (perf) ⚡️
测试 (test) ✅
杂务 (chore) 🔧
构建 (build) 📦
CI (ci) 💚
回滚 (revert) ⏪

变更记录

遵循 Keep a Changelog。编辑文档或设计规范时，需在 CHANGELOG.md 中同步追加条目（按 Added / Changed 分类）。

内容与隐私

  • 示例不得包含真实学生信息、账号、访问令牌、内部接口或未授权资料；示例数据一律使用占位内容。
  • 涉及标识、图片完整性与品牌独立的政策，见品牌使用政策与来源与非官方声明。

治理

Logo、品牌名称、主色和授权边界由组织维护者评审批准。高影响变更的评审与版本策略见贡献与变更。