感谢您抽出时间为MDN Web文档! 🎉
本文档涵盖了项目设置步骤以及一组用于贡献MDN Web文档内容的准则。每个参与该项目的人都应该关注我们的行为准则,这意味着坚持Mozilla社区参与指南.如果您想直接跳进去,请参阅MDN Web文档入门有关如何加入的概述,以及贡献页面已筛选任务列表的MDN。
在做出贡献之前,请确保您熟悉项目指南和惯例:
- 编写指南-本页涵盖了从我们如何编写和编写内容到一般项目指南的所有内容。
- 写作风格指南-这涵盖了我们使用的语言和风格,以及我们如何编写和格式化代码示例。
- 如何在降价中写入-这涵盖了我们在MDN上支持的降价功能和我们添加的自定义扩展。
我们希望MDN的贡献者在处理内容之前对web技术有一些了解。我们汇集了相关资源,以便在发表以下内容之前了解具体主题:
关于MDN上的内容及其维护方式,需要记住以下几点:
每份文件的索引.md
从写在亚马尔.YAML由MDN构建系统读取,用于读取文档的元数据。
前面的内容必须是文件中的第一个内容,并且必须采用三行之间有效的YAML集的形式(---
).Front-matter定义文档的标题
和段塞
,还可能包括地位
,浏览器-压缩
和规范信息。下面是来自JavaScript页面:
---标题:JavaScript脚本
段塞:网络/JavaScript---
你需要GitHub帐户为MDN Web文档做出贡献。如果您对使用git和GitHub感到满意,可以跳到为MDN贡献.如果您已经创建了一个新的GitHub帐户,并想知道下一步要做什么,您可以选择以下方法之一来管理更改:
如果你想做一个小的改变,比如纠正输入错误,GitHub UI是最简单的开始方式。如果您在JavaScript登录页例如,您可以建议如下修复:
- 登录到github
- 引导到https://github.com/mdn/content
- 在本例中,查找源文件
文件/en-us/web/javascript/index.md
- 单击编辑(铅笔)按钮
从那里开始,GitHub UI将通过创建叉以及将更改提交到的分支。更改分支后,打开拉入请求您的更改将被合并。
拉取请求表示您希望审查、批准并合并到主要的
MDN存储库的分支。请参阅创建拉取请求有关成功创建和处理拉请求的更多详细信息。
如果你不确定你想做什么改变,与我们联系!
注释
您可以单击在GitHub上查看源代码链接到MDN页面底部,直接跳转到GitHub上的页面源。
如果你想对多个文件进行更改,GitHub UI的效率不是很高,因为你必须对每个想要更改的文件进行单独的拉取请求。您需要使用吉特
或者像这样的客户GitHub桌面或GitHub CLI.以下示例使用普通吉特
命令,但您可以使用上面提到的任何客户端来执行等效操作。
要分叉和克隆存储库,请执行以下操作:
-
创建分叉的mdn/内容
存储库可以自由尝试分支和更改。假设您的GitHub用户名为八角形
,您的叉子将是mdn/内容
存储库位于您的帐户中https://github.com/octocat/content
.
-
将叉克隆到本地计算机。假设您的GitHub用户名为八角形
,您可以这样做:
#从您选择的目录开始
光盘 ~/回购#克隆存储库的分支git克隆git@github.com:octocat/content.git
-
创建一个遥远的
保留你的克隆和叉子(https://github.com/octocat/content
)最新。此示例添加了一个名为上游
,但你可以命名它mdn(多功能数字网络)
或者你喜欢的其他名字。
#在克隆目录中启动
光盘 ~/回购/内容git远程添加上游git@github.com:mdn/content.git
当你跑步时git远程-v
,您将看到您有两个遥控器:上游
和起源
.这个起源
遥控器是你的叉子(https://github.com/octocat/content
)和上游
遥控器是mdn/内容
存储库。
-
经常更新叉子。您可以通过从mdn/内容
存储库并将它们合并到您的fork中。
光盘 ~/回购/内容#签出本地克隆的主分支git校验总管git获取上游#合并来自mdn存储库主分支的最新内容git合并上游/主
-
为更改创建分支。此示例创建一个名为固定式(fix-typo)
:
光盘 ~/回购/内容#签出本地克隆的主分支git校验总管#创建一个名为fix-typo的新分支git结帐-b fix-typo
前面的部分描述了如何开始使用GitHub UI对单个文件进行小更改,以及如何创建fork和克隆存储库以准备进行更大的更改。本节介绍如何在本地构建项目,以及如何准备要提交的更改。
要在本地为站点提供服务,您需要节点.js和纱线1(经典)安装。您可以通过运行以下命令来检查是否安装了这些软件:
安装Node.js和Yarn后,可以使用纱线
:
#假设你的叉子在~/reso/content
光盘 ~/回购/内容纱线
安装完所有依赖项后,可以使用启动本地预览纱线起动
:
启动后,可以在以下位置进行实时预览:http://localhost:5042/
通过添加编辑器=。。。
到.env(英语)
项目根目录中的文件。例如,要将VS Code指定为首选编辑器,请使用以下命令:
回声 'EDITOR=代码' >>.env(英语)
您可以设置编辑
将环境变量设置为您喜欢的任何编辑器。在本地浏览页面服务器时,可以按在编辑器中打开在首选编辑器中编辑当前文件。
要编辑文件并跟踪更改,应使用要素分支。要素分支是从主要的
分支,并应以您正在处理的功能命名。这样可以更容易地为您的更改提交请求。
注释
如果您的更改将包含大型、复杂或结构更改,请打开讨论。在开始大型任务之前,征求反馈意见。
-
当服务器运行时,对一个或多个进行您想要的更改索引.md
文件夹。
-
打开浏览器并导航到已更改的等效页面。如果你改变了文件/en-us/web/javascript/index.md
,您将导航到http://localhost:5042/en-us/docs/web/javascript
例如,在浏览器中。
-
通过单击检查错误显示缺陷
在每个预览页面上。您可以通过运行以下命令修复缺陷:
-
将更改提交给分支(我们的示例使用修复打字错误
分支)并将更改推送到分叉的遥控器:
#将所有文件添加到提交git添加.
#使用描述更改的消息进行提交git提交-m"修复输入错误"
#把承诺推到你的叉子上git推送#或“git-push--set-upstream-origin-fix-typo”(如果您以前没有推送此分支)
为了确保所有MDN文档都遵循相同的格式,我们同时使用更漂亮和标记下划线格式化和lint标记文件。这有助于我们在所有文档中实施统一的样式,只需最少的审阅者干预。
如果你有本地结帐并拥有安装了依赖项,或您正在使用github.dev公司,将安装预提交挂钩,在进行提交时自动运行。为了避免一些头痛,并在创作时改进工作流程,您可能希望将编辑器配置为自动运行Prettier。或者,您可以运行纱线固定:md
在命令行中手动格式化所有标记文件。
注释
自动格式化更改不适用于使用GitHub Web UI打开的请求,如“简单更改”部分.这可能导致对拉入请求的状态检查失败。如果你不确定如何解决这个问题,与我们联系! 寻求帮助。
添加新文档相对简单,尤其是如果可以从复制索引.md
类似文档的。有几件事需要记住:
- 文件必须以降价形式书写。
- 文档由
索引.md
文件。
- 如果要为名为
foo公司
,创建新文件夹文件/en-us/web/css/foo/
并将标记文件放在此文件夹中(文件/en-us/web/css/foo/index.md
).
- 文档的
索引.md
文件必须以定义标题
,段塞
,而且大多数时候,页面类型
.您可能会发现在类似文档的索引.md
.
使用纱线含量移动
命令。此命令会自动移动文件并修复重定向。您可以使用此命令,如下所示:
警告
不要编辑_重定向.txt
手动文件。请参阅重定向文档部分了解更多信息。
要使用纱线含量移动
,提供要移动的文档的段塞(例如。,学习/辅助功能
),以及其新位置的段塞(例如。,学习/A11y
).现有文档的语言环境可以作为可选的第三个参数提供(默认为英语-美国
).如果要移动的文档包含子文档(即它表示文档树),则纱线含量移动
命令将移动整个树。
假设你想把整个/en-US/学习/辅助功能
树到/英语-美国/学习/A11y
,可以按以下方式执行:
-
从新的分支开始:
光盘 ~/回购/内容#从主分支获取有关mdn/content的最新更改git获取上游git校验总管git合并上游/主#为您的工作创建一个新分支git检出-b移动-a11y
-
使用移动文件纱线含量移动
.这将删除和修改现有文件,以及创建新文件。
-
一旦文件被移动,我们还需要更新其他内容文件中对这些文件的引用。使用以下命令一次性自动更新所有引用:
节点脚本/update-moved-file-links.js
-
提交所有更改并将分支推送到远程:
git添加.git提交-m"移动学习/辅助功能以学习/A11y"git推送#或git-push—设置上游原点移动-a11y
与移动文件类似,您可以使用纱线含量删除
命令。
警告
不要手动从存储库中删除文件或目录;这个纱线含量删除
命令处理必要的更改,例如更新_维基历史.json
文件。
您可以使用此命令,如下所示:
纱线含量删除<文档-插头>[locale]--重定向<重定向-插头或-url>
要使用纱线含量删除
,提供要删除的文档的段塞(例如。,学习/辅助功能
),并将区域设置作为可选的第二个参数(默认为英语-美国
).如果要删除的页面的段塞包含特殊字符,请将其括在引号中。例如:
纱线含量删除"词汇表/Round_Trip_Time_(RTT)"--重定向词汇表/延迟
如果文档有子文档(即,文档表示文档树),则必须指定-r、 --递归
选项,否则命令将失败。假设您想删除整个/en-US/学习/辅助功能
树并将所有删除的文档重定向到网络/辅助功能
。您可以执行以下步骤:
-
从新鲜的树枝开始。
光盘 ~/回购/内容#从主分支获取对mdn/content的最新更改git获取上游git校验总管git合并上游/主#为您的工作创建一个新分支git checkout-b删除-a11y
-
运行纱线含量删除
命令并重定向所有已删除的文档。
纱线内容删除学习/辅助功能--递归--重定向Web/辅助功能
[!警告]删除文档时应始终添加重定向。如果没有明显的替代方法,请重定向到所删除主题最近的“父级”。如果删除文件时忘记重定向,可以在以后执行。请参阅重定向文档第节。
-
提交所有更改并将分支推送到远程。
git添加.git提交-m"删除学习/辅助功能页面"git推送#或git-push—设置流原点移动-a11y
如果你是移动文档如上所示,您不需要创建重定向。然而,在修复断开的链接时或之后,您可能需要这样做删除文档没有--重定向
标志。
您可以使用纱线含量增加
命令。
-
创建一个新的分支机构:
光盘 ~/回购/内容#从主分支获取有关mdn/content的最新更改git获取上游git校验总管git合并上游/主#为您的工作创建一个新分支git checkout-b删除-a11y
-
使用添加重定向纱线含量增加
。目标页面可以是MDN上的页面或外部URL:
纱线含量add-redirect/en-US/path/of/deleted/page/en-US/path/of/target/page
-
提交所有更改的文件并将分支推到分支:
git添加.git提交-m"删除学习/辅助功能页面后添加重定向"git推送#或git-push—设置流源删除-a11y
一旦您做出了更改并将其推送到分叉上的分支,您就可以创建拉请求提出您对mdn/内容
存储库。MDN团队或MDN Web文档社区的人员将审查您的更改并提供反馈。
有关下一步操作的详细信息,请参阅拉请求礼仪部分了解如何处理拉取请求并成功合并内容。
这是为MDN贡献的令人兴奋的部分,因为您几乎完成了贡献过程!此时需要记住以下几点:
- 您的提款请求必须是审查和批准在合并到
主要的
分支。
- 您不需要请求审阅; 将自动为您选择一个或多个审阅者。
- 最长可达48小时将合并的拉请求的更改发布到MDN Web文档.
在审查期间,您可能会被要求回答有关您的工作的问题或对建议的编辑进行更改。这是在开源项目中进行更改过程的常见部分。在复习阶段,有一些重要的礼仪规则需要记住。
-
检查测试为拉取请求自动运行的(请参阅.github/工作流).如果其中一个或多个测试失败,则必须修复它们。如果测试失败,您的拉入请求将不会被批准和合并。如果您不知道如何解决潜在问题,可以寻求帮助。
-
解决冲突如果您的拉请求与合并冲突主要的
分支。这通常通过合并主要的
分支到要素分支(吉特拉上游总管
),然后将更新的分支推送到分叉(git推送
).
-
分组逻辑更改在每个pull请求中,使其包含单个更改或相关的更改集。如果拉取请求变得太大或包含太多不相关的更改,审阅者可能会关闭您的拉取请求,并要求您为每组更改提交一个新的拉取申请。
-
不要重新打开拉请求由审核人员关闭。
-
不要使用git数据库
属于主要的
在你的树枝上。此时,您的更改将在当前主分支的顶部重播。这可能会让审查人员感到困惑,因为GitHub上的通知毫无结果。
当您对内容进行贡献时,您同意授权您的贡献根据我们的执照.