Skip to content

docs: 完善 Git 入门与贡献协作指南 - #20

Merged
Qiyuanqiii merged 1 commit into
mainfrom
docs/expand-git-basics
Sep 3, 2026
Merged

Qiyuanqiii merged 1 commit into
mainfrom
docs/expand-git-basics

Conversation

@Qiyuanqiii

@Qiyuanqiii Qiyuanqiii commented Sep 3, 2026 •

Copy link
Copy Markdown
Member

背景

原 Git 入门 页面只有少量基础命令,尚未覆盖安装、首次身份配置、工作区与暂存区、分支协作、Fork、Pull Request 和安全恢复。原 如何贡献 页面同时存在旧个人仓库地址与截图、强制 root/SSH 流程、git add .、非快进同步以及 npm/pnpm 混用等问题,新贡献者按顺序操作时容易卡住或夹带无关改动。

本 PR 将两页整理为一条面向零基础学生和 SCSWiki 贡献者的完整、安全且可按顺序执行的协作路径。

主要修改

1. 扩展 Git 入门页

  • 补充 Windows、macOS、Debian/Ubuntu、Fedora 和 Arch Linux 的安装方式与版本检查;
  • 补充作者名、公开邮箱/GitHub noreply 邮箱、默认分支和共享电脑上的隐私提醒;
  • 解释工作区、暂存区、本地仓库、远程仓库以及 add / commit / push / PR 的边界;
  • 增加一次性练习仓库,以及 status → diff → 精确暂存 → staged diff → commit 的安全工作流;
  • 增加任务分支、Fork、origin / upstream、--ff-only 同步、推送和创建/更新 PR;
  • 增加取消暂存、丢弃未暂存修改、git revert、危险命令警示、常见报错和完成自查;
  • 将内容状态更新为 verified,并加入 Git、Pro Git 和 GitHub 官方来源。

2. 重写贡献协作流程

  • 将仓库地址统一为 CWNU-Open-Source-Community/SCSWiki,移除仍指向旧个人仓库的过时截图;
  • 明确 YOUR-USERNAME、实际文件路径和任务分支都需要替换,避免把占位内容直接复制到终端;
  • 补充 Node.js >=20.11.0、Corepack、仓库锁定的 pnpm 9.15.4、依赖安装和 pnpm dev;
  • 说明开发服务器会占用终端,并引导使用第二终端或按 Ctrl+C 停止;
  • 将强制 root/SSH 改为 HTTPS 与 SSH 二选一,并提前说明 GitHub 认证和凭据安全;
  • 使用 git merge --ff-only、明确文件暂存和 git diff --staged,不再把 git add . 作为默认流程;
  • 将演示任务改为更新已有页面,避免覆盖现有文件或重复添加侧边栏;
  • 统一 Commit、PR 创建、评审更新以及合并后本地/远程分支清理的顺序。

3. 更新入口与移动端元信息

  • 同步更新开发环境总览中 Git 页面的范围说明;
  • 为 <=640px 的 ContentMeta 卡片增加紧凑两列布局;
  • 让来源项占满整行,并为长名称和 URL 增加安全换行,减少手机端纵向占用和横向溢出。

安全与变更边界

  • 仅修改 4 个文件:
    • docs/development/git-basics.md
    • docs/development/index.md
    • docs/about/contribute.md
    • docs/.vitepress/theme/custom.css
  • 不修改页面 URL,不移动内容,不新增依赖,不修改 API、CI 或部署配置;
  • 不引导直接修改 main、强制推送、使用 root 运行项目命令或在远程地址中保存令牌;
  • --ff-only 在本地 main 已分叉时会主动失败,这是避免意外合并提交的保护行为。

验证

本地已完成:

  • pnpm typecheck
  • pnpm lint:md(110 个 Markdown 文件,0 错误)
  • 对本 PR 4 个文件执行 Prettier 检查
  • pnpm validate:content(100 个 Markdown 文件)
  • pnpm check:materials(86 个资料文件)
  • pnpm check:links(100 个 Markdown 文件)
  • pnpm test(6 个测试文件、24 项测试)
  • pnpm build
  • 检查新增 Git/GitHub/Node.js 官方链接可访问
  • 桌面端及 390px、320px 移动端检查 Git 页面和 ContentMeta;同时抽查多警告、多来源与特殊覆盖页面
  • GitHub Actions CI(pnpm check)

生产构建仅保留仓库已有的“大于 500 kB chunk”警告,没有新增构建错误。

风险与回滚

改动集中在文档和 <=640px 的 ContentMeta 样式,不影响桌面布局或站点数据。若需要回滚,可直接 revert 本 PR 的文档提交;无数据迁移或额外清理步骤。

@Qiyuanqiii
Qiyuanqiii merged commit 693e545 into main Sep 3, 2026
1 check passed
@Qiyuanqiii
Qiyuanqiii deleted the docs/expand-git-basics branch September 3, 2026 22:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant