为 Fastify 做贡献

¥Contributing To Fastify

感谢你有兴趣为 Fastify 做出贡献。我们很高兴得到你的支持和知识。本指南旨在帮助你帮助我们。

¥Thank you for taking an interest in contributing to Fastify. We are excited to receive your support and knowledge. This guide is our attempt to help you help us.

注意

¥Note

这是一份非正式指南。请查看正式的 贡献文档 以了解完整详情和我们的 开发者来源证书。

¥This is an informal guide. Please review the formal CONTRIBUTING document for full details and our Developer Certificate of Origin.

目录

¥Table Of Contents

• 目录

  ¥Table Of Contents

• 我们正在寻找的贡献类型

  ¥Types Of Contributions We're Looking For

• 基本规则和期望

  ¥Ground Rules & Expectations

• 如何贡献

  ¥How To Contribute

• 设置你的环境

  ¥Setting Up Your Environment

  • 使用 Visual Studio 代码

    ¥Using Visual Studio Code

我们正在寻找的贡献类型

¥Types Of Contributions We're Looking For

简而言之，我们欢迎你愿意提供的任何类型的贡献。任何贡献都不算太小。我们很乐意接受以下贡献：

¥In short, we welcome any type of contribution you are willing to provide. No contribution is too small. We gladly accept contributions such as:

• 文档改进：从小的错字更正到主要的文档返工

  ¥Documentation improvements: from small typo corrections to major document reworks

• 通过回答拉取请求和 discussions 中的问题来帮助他人

  ¥Helping others by answering questions in pull requests and discussions

• 修复 已知的错误

  ¥Fixing known bugs

• 通过以最少的重现提出问题来报告以前未知的错误

  ¥Reporting previously unknown bugs by opening an issue with a minimal reproduction

基本规则和期望

¥Ground Rules & Expectations

在我们开始之前，以下是我们对你的期望（以及你应该对其他人的期望）：

¥Before we get started, here are a few things we expect from you (and that you should expect from others):

• 在围绕该项目的对话中要尊重并深思熟虑。该项目由来自全球各地的不同人员维护。每个人对项目都有自己的看法和看法。尝试互相倾听并达成一致或妥协。

  ¥Be respectful and thoughtful in your conversations around this project. This project is maintained by a diverse set of people from all across the globe. Each person has their own views and opinions about the project. Try to listen to each other and reach an agreement or compromise.

• 我们有一个 行为守则。你必须遵守它才能参与此项目。

  ¥We have a Code of Conduct. You must adhere to it to participate in this project.

• 如果你打开拉取请求，请确保你的贡献通过所有测试。如果存在测试失败，你需要先解决这些问题，然后我们才能合并你的贡献。

  ¥If you open a pull request, please ensure that your contribution passes all tests. If there are test failures, you will need to address them before we can merge your contribution.

如何贡献

¥How To Contribute

如果你想做出贡献，请先搜索 issues 和 拉取请求，看看是否有人提出了类似的想法或问题。

¥If you'd like to contribute, start by searching through the issues and pull requests to see whether someone else has raised a similar idea or question.

如果你没有看到列出的想法，并且你认为它符合本指南的目标，请执行以下操作之一：

¥If you don't see your idea listed, and you think it fits into the goals of this guide, do one of the following:

• 如果你的贡献很小，例如拼写错误修复，请打开拉取请求。

  ¥If your contribution is minor, such as a typo fix, open a pull request.

• 如果你的贡献很大，例如新功能，请先打开一个问题。这样，其他人就可以在你做任何工作之前参与讨论。

  ¥If your contribution is major, such as a new feature, start by opening an issue first. That way, other people can weigh in on the discussion before you do any work.

设置你的环境

¥Setting Up Your Environment

请遵守项目的代码和文档风格。一些自动 "correct" 代码和文档的流行工具不遵循符合此项目使用的样式的样式。值得注意的是，该项目使用 StandardJS 进行代码格式化。

¥Please adhere to the project's code and documentation style. Some popular tools that automatically "correct" code and documentation do not follow a style that conforms to the styles this project uses. Notably, this project uses StandardJS for code formatting.

使用 Visual Studio 代码

¥Using Visual Studio Code

接下来是如何使用 Visual Studio Code (VSCode) 可移植 创建特定于 Fastify 的环境。本指南的编写方式就像你在 macOS 上设置环境一样，但所有平台的原理都是相同的。有关其他平台的帮助，请参阅之前链接的 VSCode 可移植指南。

¥What follows is how to use Visual Studio Code (VSCode) portable to create a Fastify specific environment. This guide is written as if you are setting up the environment on macOS, but the principles are the same across all platforms. See the previously linked VSCode portable guide for help with other platforms.

首先，下载 VSCode 并将其解包到 /Applications/VSCodeFastify/。这样做后，在终端中运行时，以下内容应输出 "found"：

¥First, download VSCode and unpackage it to /Applications/VSCodeFastify/. Upon doing so, the following should output "found" when run in a terminal:

[ -d /Applications/VSCodeFastify/Visual\ Studio\ Code.app ] && echo "found"

正如 VSCode 便携指南中提到的，我们需要对应用取消沙箱处理，以便便携模式正常工作。因此，在终端中发出以下命令：

¥As mentioned in the VSCode portable guide, we need to unsandbox the application for the portable mode to work correctly. So issue the following in a terminal:

xattr -dr com.apple.quarantine /Applications/VSCodeFastify/Visual\ Studio\ Code.app

接下来，创建 VSCode 所需的数据目录：

¥Next, create the required data directories for VSCode:

mkdir -p /Applications/VSCodeFastify/code-portable-data/{user-data,extensions}

在继续之前，我们需要将 code 命令添加到终端的 PATH。为此，我们将 手动将 VSCode 添加到 PATH。正如该文档中所述，说明根据你的默认 shell 的不同而有所不同，因此你应该遵循该指南中与你的首选 shell 相关的说明。但是，我们将通过定义别名而不是直接引用 code 工具来对其进行稍微调整。这样我们就不会与你可能拥有的任何其他 VSCode 安装发生冲突，并使本指南专门针对 Fastify。因此，最终我们想要以下内容：

¥Before continuing, we need to add the code command to your terminal's PATH. To do so, we will manually add VSCode to the PATH. As outlined in that document, the instructions vary depending on your default shell, so you should follow the instructions in that guide as relates to your preferred shell. However, we will tweak them slightly by defining an alias instead of a direct reference to the code tool. This is so we do not conflict with any other installation of VSCode you may have, and to keep this guide specific to Fastify. So, ultimately, we want the following:

alias code-fastify="/Applications/VSCodeFastify/Visual\ Studio\ Code.app/Contents/Resources/app/bin/code"

结果应该是 code-fastify --version 产生类似以下内容的结果：

¥The result should be that code-fastify --version results in something like:

❯ code-fastify --version
1.50.0
93c2f0fbf16c5a4b10e4d5f89737d9c2c25488a3
x64

现在 VSCode 已安装，我们可以通过命令行使用它，我们需要安装一个扩展，该扩展将有助于保持你为项目编写的任何 JavaScript 根据项目的风格进行格式化：

¥Now that VSCode is installed, and we can work with it via the command line, we need to install an extension that will aid in keeping any JavaScript you write for the project formatted according to the project's style:

code-fastify --install-extension dbaeumer.vscode-eslint

成功执行上一个命令后，以下命令应导致输出 "found"：

¥Upon successful execution of the previous command, the following command should result in "found" being output:

[ -d /Applications/VSCodeFastify/code-portable-data/extensions/dbaeumer.vscode-eslint-* ] && echo "found"

现在，从 Fastify 项目的本地克隆目录中，我们可以打开 VSCode：

¥Now, from within the directory of your local clone of the Fastify project, we can open VSCode:

code-fastify .

应打开一个新的 VSCode 窗口，你应在左侧边栏中看到 Fastify 项目文件。可是等等！我们还没有完全完成。在 VSCode 准备就绪之前，还应设置一些基线设置。

¥A new VSCode window should open and you should see the Fastify project files in the left sidebar. But wait! We are not quite done yet. There are a few more baseline settings that should be set before VSCode is ready.

按 cmd+shift+p 调出 VSCode 命令输入提示符。类型 open settings (json)。下拉菜单中将出现三个 VSCode 设置 选项：工作区、默认和用户设置。我们建议选择默认。这将打开一个包含编辑器设置的文档。将以下 JSON 粘贴到此文档中，覆盖任何已存在的文本，然后保存：

¥Press cmd+shift+p to bring up the VSCode command input prompt. Type open settings (json). Three VSCode Setting options will appear in the dropdown: Workspace, Default, and User settings. We recommend selecting Default. This will open a document that is the settings for the editor. Paste the following JSON into this document, overwriting any text already present, and save it:

{
    "[javascript]": {
        "editor.defaultFormatter": "dbaeumer.vscode-eslint",
        "editor.codeActionsOnSave": {
            "source.fixAll": true
        }
    },

    "workbench.colorCustomizations": {
        "statusBar.background": "#178bb9"
    }
}

最后，从菜单栏中选择 "终端 > 新终端" 以在编辑器中打开一个新终端。运行 npm i 以安装 Fastify 依赖。

¥Finally, from the menu bar, select "Terminal > New Terminal" to open a new terminal in the editor. Run npm i to install the Fastify dependencies.

此时，你已设置好一个自定义 VSCode 实例，可用于处理 Fastify 贡献。当你编辑和保存 JavaScript 文件时，编辑器将自动更正任何样式问题。

¥At this point, you are all setup with a custom VSCode instance that can be used to work on Fastify contributions. As you edit and save JavaScript files, the editor will autocorrect any style issues.