search
Vercel 镜像站VitePress 镜像站QQ 群 787969044视频教程Ⅰ视频教程Ⅱ
github编辑

贡献指南与开放任务

hashtag
为什么不去建设《FreeBSD 手册》

FreeBSD 项目拒绝（表现为长期搁置）任何实质上的 PR，除了季度报告。事实上，纵观提交数据，freebsd doc 项目已经死亡十余年：

使用 统计分析 git 项目arrow-up-right 备份arrow-up-right 对 freebsd-doc 进行分析的结果参见 freebsd-doc-2025 分析报告arrow-up-right 备份arrow-up-right。

  • 2005-2006 年：第一次显著下滑

  • 2015-2016 年：第二次大幅下滑

项目结构复杂且混乱。维护者自己都看不懂。比如在翻译时的某些数据引用是否可复用。

由于其安全报告的文件名在 Windows 下是非法字符（有英文冒号 :），因此导致整个项目无法在 Windows 下正常拉取：

PS C:\Users\ykla> git clone https://github.com/freebsd/freebsd-doc
Cloning into 'freebsd-doc'...
remote: Enumerating objects: 617155, done.
remote: Counting objects: 100% (294/294), done.
remote: Compressing objects: 100% (120/120), done.
remote: Total 617155 (delta 217), reused 219 (delta 174), pack-reused 616861 (from 4)
Receiving objects: 100% (617155/617155), 483.71 MiB | 786.00 KiB/s, done.
Resolving deltas: 100% (358420/358420), done.
error: invalid path 'website/static/security/advisories/FreeBSD-EN-04:01.twe.asc' # 观察 FreeBSD-EN-04:01.twe.asc，该文件名在 Windows 下是非法的
fatal: unable to checkout working tree
warning: Clone succeeded, but checkout failed.
You can inspect what was checked out with 'git status'
and retry with 'git restore --source=HEAD :/'

hashtag
贡献指南概述

如果你想让你的教程出现在本书中，你可以这样做：

  • 如果你熟悉 GitHub，可以点击电脑端右侧的“编辑此页”，进入项目进行操作。整个项目使用 Markdown 语法 + Gitbook，简单易上手（具体详见项目 WiKi）；

  • 如果以上有困难，你还可以发 PDF、Word 或者 TXT 给我。请将文件发送至电子邮件 [email protected]（我将在 3 天内回复。若我没有回复，请换个邮件再发一次，或者提交 issue）；如果有视频教程，以各大云盘链接为宜。

本书现接受以下内容：

  • 一切与 BSD 相关（包括不限于 FreeBSD，OpenBSD，NetBSD）以及各种体系结构的教程。你既可以扩充当前教程，也可以新建一节；

  • 下方的 ToDo 列表或 GitHub Project；

  • 你亦可在文学故事章节分享你与 BSD 的故事，你的个人心得体会。

hashtag
基本原则与方法论

hashtag
基本原则

hashtag
使之成为“一本书”，而不仅仅是本字典或手册

  • 如果某一技术在最新版本被移除，则应及时移除其在本书的对应位置内容

  • 使全书语气温柔而坚定

  • 在最大化减少原文引用的前提下，重写各章节内容，删除冗余。

  • 现代化、简化 BSD 中文文档协作方式：

    • 自动化（CI 检查、预览、生成 HTML/PDF）

    • 仅用最基础的 Markdown 语法，避免复杂扩展和繁琐流程

    • 技术和选材与时俱进，确保内容现代化。

  • 严格验证每一部分：

    • 参考文献：不仅要求来源可查，而且要求来源可信：

    • 原理性内容：

      • 追溯到具体 FreeBSD 源码文件、提交记录或函数；

      • 具体到相关标准、规范、法律文件等

      • 分析其设计哲学与开发思路

    • 操作性内容：在 FreeBSD 环境中亲自试验，确保可复现

  • 审视原作者的开发哲学与理念，评价其合理性，并尝试简单参与相关项目。

  • 指出并修正上游官方手册中的错误或已过时内容。

  • 生成英文版本

hashtag
细则

  • 非拉丁字符与拉丁字符间应该加空格（中英文/数字间应有一个半角空格），有许多 Markdown 格式化工具可以自动完成。

  • 不应该使用 sudo 而应该用 # 代替，除非特例（如讲解如何使用 sudo 本身）；普通用户权限请使用 $ 表示。

  • 安装软件时，给出 pkg 或 ports 两种方法，除非极不建议使用 pkg，如特定内核模块等。

  • 请注意版权问题。引用或灵感受到启发时，请备注文章链接出处，必要时可使用互联网档案馆进行快照保存。

  • 编辑时尽量以最新的 FreeBSD RELEASE 为基准，绝对避免出现 pkg_add 此类过时东西。如有必要，必须予以注明版本。

  • 对于编写时长问题，理论上会一直持续下去，跟随每个 FreeBSD 大版本迭代。

  • 由于种种原因，无法立即验证所写内容是否正确无误时，请编辑者打上“警告：以下内容为理论，未经实际测试，仅供参考，如果可以使用请提交 issue 以移除本标签。”标签以作区分。

  • 不应该对文学故事章节进行除错字排版以外的删减。

  • 请勿使用诸如 Gitee 等境内无法确保信息安全与数据稳定的平台（这类平台无法保证留存文件的长久可访问性，不适合存放适用于长期归档的内容，在未来会有极大风险无法获取该文件）。

  • 当进行错别字修改时，请务必确证其的确是错别字，可参考《现代汉语词典》第 7 版等资料进行佐证。

hashtag
实用附录

hashtag
如何使用 git 拉取本项目

技巧

理论上你完全可以通过 GitHub 在线完成所有提交。

本项目太大，使用 git 拉取时可能会导致缓冲区溢出，可改变 git 配置文件，以实现对缓冲区的扩大：

以下是一个可用的 ~/.gitconfig（Windows 上的位置为 C:\Users\你的用户名\.gitconfig） 的文件示例：

名词解释：

拉取命令：

hashtag
故障排除

  • 致命错误:无法访问 'https://github.com/FreeBSD-Ask/FreeBSD-Ask/': Recv failure: 连接被对方重置

请尝试拉取这个项目 https://github.com/FreeBSD-Ask/LDWG。

如果报错类似，说明你的网络有问题。请使用代理。

hashtag
项目简介

本项目是主项目（即 https://book.bsdcn.org）托管在 Gitbook；

https://docs.bsdcn.org 是社区自行构建的，docs 网站本身的贡献指南参见 FreeBSD 从入门到跑路 VitePress 镜像项目arrow-up-right 备份arrow-up-right。

技巧

如果你仅想贡献内容本身，尚无改进网站 docs 的浏览体验与构建优化等等意向，则仅需阅读本文即可。

hashtag
项目结构概览

hashtag
如何新建章节

自行操作时参见操作实例 Commit 6023cc8arrow-up-right 备份arrow-up-right 和下方 SUMMARY.md 结构说明。

如果有困难可发邮件联系 ykla 来操作。

hashtag
SUMMARY.md 目录结构

可以看到，SUMMARY.md 在形式上就是普通的 markdown 文档，并无特殊支持。

但是也有一些注意事项：

  • 第一行 # Table of contents 是绝对不允许变动的，否则 Gitbook 将无法识别，造成失去同步。

  • 我们要求应该形如 * [2.2 使用 bsdinstall 开始安装](di-2-zhang-an-zhuang-freebsd/di-2.2-jie-start-install.md)，不允许 * [2.2 使用 bsdinstall 开始安装](di-3-zhang-ni-hao/di-2.2-jie-start-install.md)，即你的目录结构和放置的文件位置必须一致。（不一致并不会出错，但是本项目要求你一致）

  • 通过 sync-headers.yml，将自动同步 SUMMARY.md 中的章节标题到具体的 markdown 文件中。因此若你要修改 di-2.2-jie-start-install.md 的一级标题 # 2.2 使用 bsdinstall 开始安装，必须只能修改 SUMMARY.md 中的 2.2 使用 bsdinstall 开始安装，否则会被 sync-headers.yml 覆盖。当二者不同时，若正好在提交时未触发脚本即构建，那么 Gitbook 将以 SUMMARY.md 中的目录为准。

hashtag
预览页面

当你提交 PR 时，会自动生成一个预览的网站。

实际上，所有提交都有对应版本的网站：

你可以通过该链接获取你当前 PR 的实际显示样式：

且每次 push 都会自动更新：

hashtag
开放任务

所有任务的排序都是随机的并无优先级之分，你可以选你喜欢的去做。

hashtag
开源社区

hashtag
维护百度百科、维基百科相关条目

如增补修订各大 BSD 中文条目。

hashtag
帮助修订 USTC 镜像脚本

hashtag
FreeBSD ToDo

不再需要 的内容（请 不要 撰写下列条目）：

Just for fun（没有也行无关紧要）

需要重写 的内容（请撰写这些内容）：

参见 Projectsarrow-up-right 备份arrow-up-right。

hashtag
NetBSD ToDo

参见 Projectsarrow-up-right 备份arrow-up-right。

hashtag
DragonFlyBSD ToDo

参见 Projectsarrow-up-right 备份arrow-up-right。

上一页编辑日志下一页目录

最后更新于