jstips 贡献指南：如何向 JS Tips 仓库提交你的 JavaScript 技巧-平芜编程栈

教程

【免费下载链接】jstips

This is about useful JS tips!

项目地址：https://gitcode.com/gh_mirrors/js/jstips

导读

本文基于 jstips 仓库的贡献规范文档（CONTRIBUTING_es_ES.md，另有英文版 CONTRIBUTING.md、简体中文版 CONTRIBUTING_zh_CN.md 与繁体中文版 CONTRIBUTING_zh_TW.md），完整讲解向该开源项目提交 JavaScript 技巧（tip）的操作流程：从 fork 仓库、按规范命名文件，到套用文章模板、发起 Pull Request，再到通过社区多人审查最终合入的完整链路。读完本文，你将掌握 jstips 投稿的每一项硬性要求（文件命名、Front Matter 字段、内容规范），以及仓库内真实示例所展示的实战写法。

jstips 是一个"两分钟内读完一条有用 JS 技巧"的开源合集（项目简介见 README.md），全部内容以 Markdown 文件形式按语言存放于 _posts 目录。贡献流程的核心是：fork 仓库 → 新建符合命名规则的文件 → 套用模板写作 → 发起 PR → 等待 5 人审查并给出→ 合入。

一、投稿的整体流程

根据贡献文档，向 jstips 提交一条 tip 需要走完以下步骤：

fork 仓库：将 jstips 复制到你的账户下；
新建文件：根据 tip 的语言，在_posts下对应语言目录中创建一个新 Markdown 文件；
按模板写作：使用 POST_TEMPLATE.md 提供的格式撰写内容；
发起 Pull Request：按照 PULL_REQUEST_TEMPLATE.md 填写 PR 信息；
等待审查：tip 进入under review状态，经 5 人审查并给出后变为ready to merge，随后合入列表。

整个状态流转可以概括为一条流水线：

Tip proposal（提交）⇒Tip under review（审查中）⇒Tip ready to merge（可合并）

二、仓库的语言目录结构与文件命名规范

2.1 目录结构

投稿的第一步是"放到正确的目录"，目录按语言划分，位于 _posts 之下：

_posts/en/：英文 tips，其中再按技术领域细分javascript/、angular/、react/、more/等子目录；
_posts/es_ES/：西班牙语 tips；
_posts/zh_CN/：简体中文 tips；
_posts/zh_TW/：繁体中文 tips。

从仓库实际内容可以看到，例如英文目录下有 _posts/en/javascript/2016-01-03-improve-nested-conditionals.md，对应的西班牙语版本位于 _posts/es_ES/javascript/2016-01-03-improve-nested-conditionals.md。如果你的 tip 是关于 React 的，就放在对应语言的react/子目录；关于 Angular 的放在angular/；无法归入以上类的通用主题放在javascript/或more/。

2.2 文件命名规则

文件名必须遵循以下格式：

2016-xx-xx-name-of-your-tip

例如：2016-01-03-improve-nested-conditionals。要点如下：

前缀是日期，格式为年-月-日；
日期和编号部分在投稿阶段保留为xx占位（详见下文"注意事项"）；
中间是用连字符连接的 tip 主题描述，即name-of-your-tip；
文件扩展名为.md。

日期与 tip 编号在投稿时先用xx占位，当 PR 被标记为ready to merge时，维护者会告知正确的编号，届时再补齐。

三、文章模板：Front Matter 字段详解

写作时必须使用 POST_TEMPLATE.md 规定的格式。该模板本质上是一个带 YAML Front Matter 的 Markdown 文件，下面结合仓库真实文章逐一说明每个字段。

3.1 标准模板结构

--- layout: *post title: Demo post tip-number: xx tip-username: tip_js tip-username-profile: https://twitter.com/tips_js tip-tldr: Just a demo <!-- tip-writer-support: Paypal, Coinbase, Etc --> <!-- tip-translator-support: Paypal, Coinbase, Etc --> categories: - en --- content here ### Subtitles format

3.2 字段含义与真实示例对照

以仓库中编号为 03 的真实文章 _posts/en/javascript/2016-01-03-improve-nested-conditionals.md 为例：

字段	含义	模板示例	真实示例
`layout`	页面布局类型	`*post`	`post`
`title`	文章标题（不得出现"JavaScript"字样）	`Demo post`	`Improve Nested Conditionals`
`tip-number`	tip 编号，投稿阶段写`xx`	`xx`	`03`
`tip-username`	作者用户名	`tip_js`	`AlbertoFuente`
`tip-username-profile`	作者主页链接	Twitter 链接	GitHub 链接
`tip-tldr`	一句话摘要（TL;DR）	`Just a demo`	`How can we improve and make a more efficient nested if statement in javascript?`
`tip-writer-support`	作者收款支持链接（可选，默认注释掉）	Paypal/Coinbase 等	可选
`tip-translator-support`	译者收款支持链接（可选）	Paypal/Coinbase 等	可选
`categories`	分类，第一项为语言（如`en`/`es_ES`/`zh_CN`/`zh_TW`），第二项为技术领域（如`javascript`/`react`）	`- en`	`- en`+`- javascript`

模板中tip-writer-support和tip-translator-support默认以 HTML 注释形式存在：如果你有 PayPal、Coinbase 或其他收款账户，把链接填进去，读者就可以为你的知识"请喝一杯啤酒"；不需要则保持注释状态即可。

3.3 正文格式

模板正文区为content here，并提示可用### Subtitles format添加子标题。真实文章的正文通常结构为：

开头用一句话点明要解决的问题（对应tip-tldr）；
用```javascript代码块展示技巧；
必要时用###级子标题分段，用文字说明原理与使用场景。

例如 03 号文章就是先抛出"如何优化嵌套if语句"的问题，再依次给出switch、switch(true)条件判断、函数重构、对象映射四种演进方案。

四、内容硬性要求

贡献文档列出了投稿必须满足的五条要求，投稿前务必逐条核对：

两分钟内可读完：tip 必须短小精悍，符合 jstips"快速学习"的定位（README 中同样强调 "In less than 2 minutes, you can read about..."）；
允许附带扩展链接：欢迎添加其他网站或视频链接，帮助读者获得更深入的理解；
代码用```js标记：所有 JavaScript 代码必须放在带js语言标识的 fenced code block 中，确保语法高亮正确；
标题中不写"JavaScript"：因为整个项目就是关于 JavaScript 的，标题无需重复（原文 "Don't mention 'JavaScript' in the title"）；
反引号规则：在title和tip-tldr字段中如需标记行内代码，必须使用反引号（`）。警告：这两个字段的值本身不能以反引号开头（"Both values must not start with backticks"）。

五、发起 Pull Request

5.1 使用 PR 模板

tip 写好后，需要以 PULL_REQUEST_TEMPLATE.md 为模板发起 Pull Request。该模板结构如下：

## [Title here] ## TL;DR; [content here] ## Username [twitter account link or github account link ej: [@tips-js](https://twitter.com/tips_js)] ## Extra [content here]

Title：本次 PR 的标题，即你的 tip 标题；
TL;DR：与 Front Matter 中tip-tldr对应的一句话摘要；
Username：你的 Twitter 或 GitHub 主页链接；
Extra：其他补充信息，可选。

5.2 审查阶段

PR 提交后即进入under review状态。仓库的审查机制如下：

每条 tip 需要经过5 人审查，且审查者都给出表情后，状态才会变为ready to merge；
审查通过后，维护者会告知正确的日期和 tip 编号，由你补全后合入列表。

六、注意事项

xx占位符：投稿期间，文件名的日期部分和 Front Matter 中的tip-number一律保留为xx，不要自行编号，避免与已有 tip 冲突；
squash 提交：请将你的多次提交压缩（squash）为一次 commit，保持提交历史整洁；
多语言支持：jstips 同时维护英文、西班牙语、简体中文、繁体中文四套内容（各语言目录见 _posts），你的投稿可以先用母语写作，也可以参考 CONTRIBUTING_zh_CN.md 等对应语言文档了解本地化要求；西班牙语投稿者请直接以 CONTRIBUTING_es_ES.md 为准。