贡献指南
这是面向所有 AdonisJS 仓库的通用贡献指南。在向任何仓库贡献之前，请仔细阅读本指南 🙏
代码并非唯一的贡献方式。以下也是参与贡献并成为社区一员的一些途径。
- 修复文档中的错别字
- 改进现有文档
- 撰写 cookbook 或博客文章来向社区其他人传授知识
- 对 issue 进行分类（triage）
- 在现有 issue 上分享你的观点
- 在 discord 和讨论论坛上帮助社区
报告缺陷
开源项目中报告的许多 issue 通常其实是提问，或是报告者自身的配置错误。因此，我们强烈建议你在报告问题之前先进行适当的排查。
如果你要报告一个缺陷，请尽可能多地包含你所编写代码的相关信息。一个 issue 从好到坏的程度大致如下。
-
完美 issue：你隔离出了底层缺陷。在仓库中创建一个失败的测试，并围绕它开一个 Github issue。
-
良好 issue：你隔离出了底层缺陷，并提供一个最小可复现的 Github 仓库。Antfu 写了一篇很好的文章《为什么需要复现》。
-
尚可的 issue：你正确地陈述了问题。分享最初产生该问题的代码，同时附上相关的配置文件以及你所使用的软件包版本。
最后但同样重要的是，按照 Github markdown 语法指南 正确地格式化每一个代码块。
-
糟糕的 issue：你把问题一股脑倒出来，指望对方会问出相关问题来帮你。这类 issue 会被自动关闭，且不作任何解释。
展开讨论
你经常想要讨论某个话题，或分享一些想法。在这种情况下，请在讨论论坛的 💡想法 分类下创建一个讨论。
传授知识
向他人传授知识是为任何社区做出贡献并赢得认可的最佳方式之一。
你可以使用讨论论坛上的 📚 Cookbooks 分类与他人分享文章。cookbooks 板块不做严格审核，唯一的例外是所分享的知识应当与项目相关。
创建 Pull Request
在投入大量时间和精力编写代码后，你的 pull request 却被拒绝，这种体验绝不好受。因此，我们强烈建议你在自己开始任何新工作之前，先发起一个讨论。
只需发起一个讨论，并说明你打算贡献什么？
-
你是否打算创建 PR 来修复缺陷：一旦缺陷被确认，针对缺陷的 PR 大多会被接受。
-
你是否计划添加新功能：请详尽说明为何需要此功能，并分享可供我们阅读学习的资料链接。
例如：如果你正在为 Japa 或 AdonisJS 添加对快照测试（snapshot testing）的支持，那么请分享我能用来了解快照测试的链接。
注意：你还应当准备好提交额外的 PR 来为所贡献的功能或改进编写文档。
仓库设置
-
首先将仓库克隆到你的本地机器。
git clone <REPO_URL> -
在本地安装依赖。请勿随功能请求一起更新任何依赖。如果你发现过时的依赖，请创建一个单独的 PR 来更新它们。
我们使用
npm管理依赖，因此请勿使用yarn或其他工具。npm install -
通过执行以下命令运行测试。
npm test
使用的工具
以下是所使用的工具列表。
| 工具 | 用途 |
|---|---|
| TypeScript | 所有仓库均使用 TypeScript 编写，编译后的 JavaScript 与类型定义会发布到 npm 上。 |
| TS Node | 我们使用 ts-node 在未编译 TypeScript 的情况下运行测试或脚本。ts-node 的主要目标是在开发过程中获得更快的反馈循环 |
| SWC | SWC 是一个基于 Rust 的 TypeScript 编译器。TS Node 对使用 SWC 替代 TypeScript 官方编译器提供了一流支持。使用 SWC 的主要原因是速度提升。 |
| Release-It | 我们使用 release-it 在 npm 上发布我们的软件包。它承担了创建 release 并将其发布到 npm 和 Github 的所有繁重工作。其配置定义在 package.json 文件中。 |
| ESLint | ESLint 帮助我们在有多个贡献者的所有仓库中强制执行一致的编码风格。我们所有的 ESLint 规则都发布在 eslint-plugin-adonis 软件包下。 |
| Prettier | 我们使用 prettier 来格式化代码库，以获得一致的视觉输出。如果你对为何同时在使用 ESLint 和 Prettier 感到困惑，请阅读 Prettier 网站上的 Prettier vs. Linters 文档。 |
| EditorConfig | 每个项目根目录下的 .editorconfig 文件会配置你的代码编辑器，使用一组关于缩进和空白字符管理的规则。同样，Prettier 用于事后格式化你的代码，而 EditorConfig 用于提前配置编辑器。 |
| Conventional Changelog | 所有仓库中的提交都使用 commitlint 来强制执行一致的提交信息。 |
| Husky | 我们使用 husky 在提交代码时强制执行提交规范。Husky 是一个用 Node 编写的 git hooks 系统 |
命令
| 命令 | 描述 |
|---|---|
npm run test | 使用 ts-node 运行项目测试 |
npm run compile | 将 TypeScript 项目编译为 JavaScript。编译输出写入 build 目录 |
npm run release | 使用 np 启动发布流程 |
npm run lint | 使用 ESlint 检查代码库 |
npm run format | 使用 Prettier 格式化代码库 |
npm run sync-labels | 将 .github/labels.json 文件中定义的标签与 Github 同步。此命令仅限项目管理员使用。 |
编码风格
我们所有的项目都使用 TypeScript 编写，并正在向纯 ESM 迁移。
- 你可以在此处了解更多关于我的编码风格
- 查看我所遵循的 ESM 与 TypeScript 设置
同时，请确保在推送代码之前运行以下命令。
# Formats using prettier
npm run format
# Lints using Eslint
npm run lint
获得贡献者身份认可
我们依赖 GitHub 在仓库右侧面板中列出所有仓库贡献者。以下是相同内容的示例。
此外，我们使用 Github 的自动生成发布说明功能，它会在发布说明中添加对贡献者个人资料的引用。