贡献方式
USC Wiki 有哪些参与共建的路径，以及如何找到适合自己的贡献方式
USC Wiki 是南华大学学生自发维护的校园知识库。它不需要每个人都是程序员——把你已经踩过的坑写下来，就是最有价值的贡献。
本文介绍几种常见的参与方式，你可以按自己的时间和技能选一条开始。具体怎么写文档、怎么提 PR，请看 贡献指南。
我想贡献，但不知道从哪开始
可以先问自己三个问题：
- 我有什么？ 官方通知 PDF、课程经验、办事流程、软件教程……
- 我有多少时间？ 10 分钟纠错、1 小时写一节、长期维护某一类文档？
- 我会不会 Git？ 不会也没关系，仍有低门槛的参与方式。
下面按门槛从低到高排列，任选其一即可。
方式一：反馈与线索（零门槛）
适合：不想写 Markdown、不熟悉 Git，但发现了问题或有资料想分享的同学。
可以做什么
| 动作 | 示例 |
|---|---|
| 纠错 | 某页选课时间过期、链接打不开、信息明显有误 |
| 提建议 | 「希望增加 XX 课攻略」「XX 板块应该单独成页」 |
| 提供原始材料 | 教务处通知、学院群文件、课程作业要求、截图 |
| 口头分享经验 | 在群里回答「这门课怎么过」「实习怎么找」 |
去哪里反馈
- GitHub Issues — 报 Bug 或提文档/功能建议
- GitHub Discussions — 讨论结构、分享经验
- QQ 交流群 — 群号 983137123
- 邮件 — 见 加入社区
不会写 Wiki 也没关系
把 PDF、Word 或文字说明发到群里或 Issue，说明「建议更新到 XX 页面」，维护者可以代为整理入库。
方式二：撰写与补充文档（推荐）
适合：愿意写一点文字、希望内容长期留在站上的同学。这是 Wiki 最核心、最常见的贡献形式。
2.1 补全「待补充」页面
站点里已有不少占位页，目录和目标都写好了，只差内容。例如：
打开页面，若看到「待补充」提示，可以直接在该页面上补充，或新建分支修改后提 PR。
2.2 新建单篇攻略
如果你在某门课、某项竞赛或某个办事流程上有经验，可以单独写一篇文档。
| 你熟悉的内容 | 建议目录 |
|---|---|
| 某门课的考核方式、作业、避坑 | docs/学习指南/课程攻略/ |
| 选课、GPA、教材、教务通知 | docs/学习指南/教务指南/ |
| 竞赛报名与备赛 | docs/竞赛与资源/竞赛/ |
| 软件、账号、工具教程 | docs/竞赛与资源/使用教程/ |
| 报销、驾照、研学等流程 | docs/事务办理/ |
| 校园网、校历、入学相关 | docs/新生入门/ |
| 本院培养方案、专业介绍 | docs/学习指南/学院与专业/ |
完整目录说明见 贡献指南 › 文档放哪里。
2.3 维护时效性信息
有些内容每学期都会变，定期更新同样重要：
- 公共选修课 / 体育选课时间与规则
- 教材选用时间与操作
- 校园网资费与办理渠道
- 校历与开学安排
写法建议：正文标明 「截至 yyyy 年 mm 月」 或 「20XX 学年 XX 学期参考」；若有官方 PDF，放入同目录的 attachments/ 并在文末链接。
2.4 上传资料与附件
历年试卷、实验报告模板、任务书、官方通知等，可以：
- 文件放入文档旁的
attachments/（或docs/学习指南/attachments/等共享目录） - 在对应页面用 Wiki 链接引用：
[[文件名.pdf]] - 图片可用：
![[截图.png|240]]
构建时会自动同步到站内 /vault/，供其他同学下载。
写作小建议
- 优先写 「怎么做」 和 「注意什么」，少写空泛介绍
- 不确定的内容标注「待补充」或「待核实」，不要编造
- 不要提交学号、密码、身份证等隐私信息
- 引用他人资料请注明来源
- 可从
docs/_templates/页面模板.md复制起步
方式三：Git 协作（标准开源流程）
适合：愿意 Fork 仓库、本地预览、通过 Pull Request 合并的同学。
下面先说明 提交 PR 有哪几种做法，再介绍通用注意事项。
提交 PR 的几种方式
| 方式 | 适合谁 | 是否需要本地装环境 | 典型场景 |
|---|---|---|---|
| A. 本地开发 + Fork + PR | 会一点 Git，想改完先预览 | 是 | 多篇文档、上传附件、改样式/代码 |
| B. GitHub 网页直接编辑 | 不想配 Node/pnpm | 否 | 改错别字、更新一行时间、小段落补充 |
| C. GitHub Desktop 等图形工具 | 不熟悉命令行，但想本地改文件 | 可选 | 新建 .md、批量改文档 |
| D. GitHub CLI | 习惯终端、想少点网页操作 | 是 | 经常提 PR 的同学 |
| E. 请人代提 PR | 有内容但不会 Git | 否 | 把文字/PDF 交给维护者整理入库 |
A. 本地开发 + Fork + PR（推荐）
最完整、也最稳妥的方式，改代码或上传附件时都建议用这个。
- Fork GitHub 仓库，clone 到本地
- 新建分支，例如
docs/update-pe-guide - 安装依赖并本地预览：
pnpm install
pnpm dev- 修改
docs/下文档（及attachments/附件），浏览器打开http://localhost:3000检查效果 - 提交前执行构建，确认无报错：
pnpm build- 推送到你的 Fork，在 GitHub 上 Compare & pull request 向原仓库提 PR
分支命名建议
文档类用 docs/简述，修 Bug 用 fix/简述，功能类用 feat/简述，方便维护者一眼看懂。
B. GitHub 网页直接编辑
不用安装 Node、pnpm、Git，在浏览器里就能提 PR，适合只改一两个文件的小改动。
- 打开 仓库，点击右上角 Fork（首次需要）
- 进入要改的文件，例如
docs/学习指南/教务指南/选课指南.md - 点击文件右上角的 铅笔图标（Edit）
- 在网页编辑器里修改内容
- 页面下方填写提交说明，选择 Create a new branch，点 Propose changes
- 在跳转页点击 Create pull request，按模板填写 PR 说明
局限：
- 不方便一次上传多个附件或新建复杂目录结构
- 本地跑不了
pnpm dev，改完后依赖 CI 构建；PR 合并前建议在预览链接里看一眼效果（见下文「PR 提交之后」）
C. GitHub Desktop 等图形工具
介于「纯网页」和「纯命令行」之间：用 GitHub Desktop（或其它 Git 图形客户端）管理提交，不用记太多命令。
- Fork 仓库后，用 GitHub Desktop Clone 到本地
- 新建分支，用 VS Code / Cursor 等编辑器改
docs/里的文件 - 在 GitHub Desktop 里写 commit message，Push origin
- 浏览器会提示 Create Pull Request，点进去补全 PR 描述即可
若只改 Markdown、不上传大附件，可以不装 pnpm，改完直接 push，等 CI 构建结果；改动较大时仍建议本地 pnpm dev 预览。
D. GitHub CLI
已安装 GitHub CLI 时，可在终端里完成 Fork、推送、开 PR：
# 首次：登录并 Fork
gh auth login
gh repo fork hzxyayaya/USC-wiki --clone
cd USC-wiki
git checkout -b docs/my-change
# …修改文件…
git add .
git commit -m "docs: 更新选课指南 2026 秋季时间"
git push -u origin HEAD
gh pr create --title "docs: 更新选课指南" --body "更新 2026 秋季公选课初选与补选时间。"gh pr create 会按仓库里的 PR 模板引导你填写；也可加 --web 在浏览器里继续编辑。
E. 请人代提 PR
如果你已经有成稿（Word、PDF、聊天记录整理），但不方便走 Git：
- 发到 QQ 群 或 GitHub Issue，说明希望更新到哪一页
- 维护者整理成 Markdown 后代为提交 PR，并在 PR 里 @ 你确认内容
这不算你自己提 PR，但同样能让内容进入 Wiki；熟悉流程后可以再自己提。
PR 提交之后
- 仓库配置了 Vercel PR 预览：PR 创建或更新后，GitHub 会在 PR 评论区自动回复 预览链接，可直接在浏览器里查看改动后的站点效果
- 维护者 Review 通过后合并；合并后正式站会在下次部署时更新
- 若 CI 构建失败，点进 PR 的 Checks 查看日志，常见原因是 Markdown 路径错误或构建报错
适合提 PR 的改动类型
- 新增或修改一篇/多篇文档
- 修正错别字、过期时间、失效链接
- 补充某目录
index.md的导航链接 - 调整页面
order排序 - 上传附件并更新引用
半成品也欢迎
frontmatter 中设置 draft: true 时，页面仅在本地 pnpm dev 可见，正式站不会发布。可以先交草稿，后续再完善。
PR 描述怎么写
打开 PR 时会自动加载模板，至少写清这三点：
- 改了什么（新增 XX 课攻略 / 更新 2026 秋选课时间）
- 对谁有用（2025 级选体育 3 的同学）
- 还有没有待补（评分细则待任课教师确认）
若对应某个 Issue，可在描述里写 Closes #123，合并后 Issue 会自动关闭。
详细步骤、frontmatter 约定、Markdown 语法见 贡献指南。
方式四：按角色长期参与
如果希望持续贡献而不是单次 PR，可以认领一种「角色」：
| 角色 | 主要负责 | 特点 |
|---|---|---|
| 资料搬运 | 收集教务处、学院通知，整理成表格入库 | 偏事实，易核实，更新频率高 |
| 课程作者 | 维护某门或某几门课的攻略 | 深度经验，一篇一课 |
| 学院代表 | 维护 学院与专业/ 下本院内容 | 覆盖本院同学需求 |
| 新生向导 | 维护新生入门、防骗、入学清单 | 每年迎新前集中更新 |
| 资料管理员 | 试卷命名、去重、补 index、整理 attachments | 让搜索和导航更好用 |
| 校对员 | 错别字、链接、日期、frontmatter | PR 小、合并快，适合新手 |
可以在 Issues 开 [认领] 标签，说明你想维护哪一块，避免多人重复写同一页。
方式五：参与站点开发（进阶）
适合：熟悉前端、愿意改代码而不仅是写文档的同学。
仓库基于 Next.js + Fumadocs，文档以 Markdown 为主，同时支持自定义扩展：
| 方向 | 大致位置 |
|---|---|
| Markdown 解析（Wiki 链接、Callout 等） | src/remark/、src/rehype/ |
| 页面样式 | src/styles/wiki-*.css、src/app/globals.css |
| 首页与文档路由 | src/app/、source.config.ts |
| 搜索体验 | scripts/build-search-index.ts、Orama |
| CI / 部署 | .github/workflows/ |
改代码后同样需要 pnpm build 通过。文档内容采用 CC BY-NC-SA 4.0，源代码采用 MIT License。
怎么选：快速对照
只有 10 分钟、改一行字？ → GitHub 网页直接编辑（方式 B）提 PR
有官方 PDF / 通知？ → 本地开发（方式 A）整理进 docs + attachments
上过某门课有心得？ → 本地或 Desktop（方式 A/C）写一篇课程攻略
完全不想碰 Git？ → QQ 群 / Issue 丢材料（方式 E）
会 Git，想长期参与？ → 本地 Fork + 认领目录（方式 A）
会前端？ → 本地开发提 UI / 插件 PR（方式 A）内容规范（摘要）
- 信息尽量准确、可验证；政策类内容注明时间范围
- 不提交隐私与账号密码
- 引用他人资料注明来源
- 一篇 PR 尽量只做一类相关改动，方便审查与合并
完整规范见 贡献指南 › 内容规范。
下一步
本文可改
这是一篇面向贡献者的说明草稿，欢迎维护者根据实际情况增删板块、补充认领机制或学期更新清单。