外观
协作与贡献流程
这份文档写给两类人:拿到仓库权限、帮忙一起优化站点的同学,以及只想通过 PR 提改动的同学。 如果你不打算碰 Git(想把材料交给别人上架),看维护指南和投稿与贡献更合适。
一、权限分三档,先对号入座
| 你的角色 | 拿到的权限 | 你能做什么 |
|---|---|---|
| 只浏览、提意见 | Read | 看代码与历史、开 Issue,改不了任何文件 |
| 长期帮忙改内容 | Write | 可以推自己的分支、提 PR,不能直推 main |
| 偶尔提个小改动 | 无需权限 | Fork 仓库 → 改成 PR(最安全的方式) |
二、main 分支有保护,改不动是设计如此
仓库主分支 main 已开启分支保护:
- 所有改动必须通过 Pull Request 合入,不能直接推送
- 至少需要 1 位维护者批准
- 改动数据文件(见第四节)时,必须由仓库所有者批准(由
CODEOWNERS强制) - 禁止强制推送(force push)、禁止删除
main - 合并后由 GitHub Actions 自动构建并发布,约 2–4 分钟上线
仓库所有者(admin)不受这条规则限制,可以直接推送——那是给紧急修站点用的例外,协作者请老实走 PR。
三、标准流程(照抄即可)
bash
# 1. 拿到仓库
git clone https://github.com/LVSUGARS/tiexiaowei-site
cd tiexiaowei-site
pnpm install
# 2. 开一个自己的分支(命名: 类型/简短说明)
git checkout -b content/add-2026-sports-meeting
# 3. 改文件,本地实时预览
pnpm dev # 打开 http://localhost:5173
# 4. 提交前自检——三项必须全绿
pnpm build # 构建通过(有报错就别推送)
pnpm run audit # 死链 + 文章目录表格式检查
git diff --check # 多余空白字符检查
# 5. 提交并推送你的分支
git add <你改的文件> # 不要 git add -A,避免带上无关文件
git commit -m "content: 新增 2026 运动会活动台账"
git push origin content/add-2026-sports-meeting- 到 GitHub 开 Pull Request,写清「改了什么 / 为什么 / 怎么验证」,等维护者批准合并。
四、这些文件别乱动
下面这些改动会直接决定站点能不能构建、数据是否可信,改之前先确认,并且必须由仓库所有者批准:
| 路径 | 为什么敏感 |
|---|---|
data/article-catalog.template.csv | 文章库的唯一数据源;列结构与顺序固定(8 列),改表头或删列会直接构建失败 |
docs/.vitepress/data/ | 维护者名单、招新横幅、首页卡片、节气与节日表;改错会全站生效 |
docs/.vitepress/appLinks.ts | 成员端 / 新生报名 / 后台的系统入口唯一配置点 |
docs/.vitepress/config.mts | 导航栏与侧边栏结构,动了会影响全站目录 |
docs/activity/、docs/department/ | 活动台账与部门年册;历史只增不改,变化本身就是档案 |
.github/ | 部署工作流与 CODEOWNERS |
五、内容硬规矩(摘自 AGENTS.md)
- 内容即 Markdown:正文放
docs/对应栏目,不写死进组件 - 文件名用英文或拼音,标题用中文(避免 URL 中文编码)
- 单篇内容不进侧栏:侧栏只到分组级,单篇文章/条目走各库列表页
- 历史不删除:年册、活动台账只增不改
- 徽章不进表格单元格和标题;占位统一用
🚧 待补加「待补充」徽章 - 图片先压缩再入库;涉及人物肖像必须经本人同意
- 依赖锁定精确版本(如 vitepress 1.6.4),不擅自升级
六、提交信息怎么写
前缀 + 一句中文说明,沿用现有习惯:
| 前缀 | 用在哪 |
|---|---|
feat: | 新功能、新模块 |
fix: | 修 bug、修样式 |
content: | 内容更新(活动、文章、部门、资料) |
docs: | 文档、教程、规划 |
chore: | 配置、脚本、杂项 |
例:content: 补充音频部广播站职责、fix: 招新页按钮无法点击
七、出问题怎么办
- 构建报错:把完整报错贴出来再问,不要带着红字强推
- 改错了:开一个新 PR 改回来,不要用 force push
- 不确定能不能动:先开 Issue 或问维护者,尤其是数据文件
- 别删历史:活动台账、年册、既有 URL 一律保留
八、找谁
维护者名单见站点维护人员,或直接在招新群/工作群里问。