跳转至

贡献方法

Warning

建设中

软件

Note

对于新人的第一次贡献（提交 pr）来说，实际上一个浏览器就足够了（好吧你可能还需要一个能够访问 GitHub 的良好网络环境），但是对于正式的的贡献来说，网页端是并不优雅的（可以类比云游戏和本地游戏），在本地你可以获得一个更加舒适、快捷的编辑体验。同时，下面一些软件也是以后学习、科研等等中非常实用、常用的工具，大概率以后你还会再与它们相见。

因此，建议新人先通读下面的步骤，然后尝试在浏览器上提交你的第一个 pr，之后你可以探索如何在本地进行测试与贡献。

你可能需要以下软件，除 git 外不是必须的，但它们很有用，可以简化下面的步骤，减少学习成本，尤其是 git 命令们。

  • Git - 本文以全默认安装为例，这时 git 使用的编辑器是 vim
  • Visual Studio Code - 强大的文本/代码编辑器
  • Python - 不用多说了吧
  • *GitHub Desktop - 不那么常用，但偶尔 git 处理 GitHub 的 repo 时会抽风，这时用 GitHub Desktop 大概率能解决问题。

步骤

TL;DR

为 LeSnow-Ye/wx-wiki 提交 pr。

具体步骤

贡献本项目需要简单的 git 知识，但这并不难，跟随以下步骤操作即可。也可以阅读 Git 部分以了解更多。

如果你是第一次进行贡献，则需要对 LeSnow-Ye/wx-wiki 进行 fork：

  1. 创建 GitHub 账号，假设你叫作 xxx
  2. 点击 LeSnow-Ye/wx-wiki 上的 fork 按钮，你会得到一个名为 xxx/wx-wiki 的 repo
  3. 在本地 git clone https://github.com/xxx/wx-wiki.git

如果不是第一次进行贡献，可能需要对上游仓库 LeSnow-Ye/wx-wiki 进行同步：

  1. 添加 LeSnow-Ye/wx-wiki 作为远程仓库：

    git remote add upstream https://github.com/LeSnow-Ye/wx-wiki.git

  2. 拉取上游仓库的更改：

    git fetch upstream

  3. 合并上游仓库的更改：

    git merge upstream/main

    git rebase upstream/main

    merge 与 rebase 的区别参见 Git。

  4. 推送更新到你的 fork：

    由于同步是在本地运行的，你可能还需要 push 回远程仓库 xxx/wx-wiki

    git push origin main

完成上述过程后，你可以开始正式地编写内容：

  1. 编辑 /docs/*/*.md
  2. 编辑 mkdocs.yml 中的 nav 部分
  3. [可选] 使用 mkdocs serve 在本地调试，参考 本地测试
  4. 编辑完成之后，使用 git add . 来将所有的文件暂存，以准备 commit (提交)
  5. 使用 git commit 命令提交这些更改（这两步可以合并为 git commit -a）

  6. 在图示窗口对提交的内容进行简要描述

    vim

    这是 vim 编辑器（又一个大坑），简要来说，按 i 进入编辑模式 (--INSERT--)，之后可以正常输入你的描述，输入 ESC 以回到命令模式，之后依次按 :wq 并回车以保存并退出。

  7. 使用 git push 命令将你的本地分支推送到你的 GitHub Fork xxx/wx-wiki

  8. 访问 https://github.com/xxx/wx-wiki，点击 “New Pull Request” 按钮，创建一个 PR (Pull Request)
  9. 等待 PR 被合并到主分支，之后将可以在 https://wx.lesnow.top 上看到更改

事实上一些软件可以减少甚至完全取缔手动输入 git 命令，以及跳过新手极其不友好的 vim 环节，比如 Visual Studio Code 或者 GitHub Desktop：

VSCode

VSCode 中的步骤 6 如下图，在 COMMIT_EDITMSG 中输入描述，保存（Ctrl + S）后关闭窗口即可。

Alt text

Git

Git 是一个分布式版本控制系统，它允许多人协同开发并跟踪文件的更改。

Warning

TODO

如何编辑

网站核心的内容是 Markdown 文件，拓展名 .md，它们是具体内容的载体，采用 Markdown 语法。你可以使用 VSCode 来编辑、预览 Markdown 文件。

网站的目录结构基本上是文件结构的映射。例如，/docs/intro/contribute.md 所对应的网页是 https://wx.lesnow.top/intro/contribute，但由于网站由中文呈现，你还需要额外编辑 /mkdocs.yml 文件以确定页面标题，参照已有内容编辑即可。

本地测试

由于在 merge 前，你并不知道你的 md 文件的最终在网页上的呈现效果，你可以在本地搭建一个测试环境：

  1. 在根目录运行命令 pip install -r requirements.txt 以安装所需的包（需要 Python 以及 pip，默认安装 Python 会同时安装 pip。只需要运行一次）
  2. 运行 mkdocs serve（VSCode 中可以按 Ctrl + Shift + ~ 打开终端）
  3. 在浏览器访问 http://127.0.0.1:8000/ 以观察渲染效果

参考 Creating your site - Material for MkDocs

评论