贡献
这是面向所有 AdonisJS 仓库的通用贡献指南。在为任何仓库做贡献之前，请仔细阅读本指南。
代码并非唯一的贡献方式。以下也是参与并融入社区的一些方式。
- 修正文档中的错别字
- 改进现有文档
- 撰写教程（cookbook）或博客文章来为社区中的其他人提供指导
- 对 issue 进行分流（triage）
- 在现有 issue 中分享你的观点
- 在 discord 和讨论论坛中帮助社区成员。
报告 bug
在开源项目上报告的许多 issue，通常其实是提问或报告者自己配置有误。因此，我们强烈建议你在报告问题之前，先对自己的问题做好排查。
如果你要报告一个 bug，请尽可能多地包含你所写代码的相关信息。从好到差的 issue 大致如下。
-
PERFECT ISSUE（完美 issue）：你隔离出了底层 bug。在仓库中创建一个失败的测试，并围绕它开启一个 Github issue。
-
GOOD ISSUE（良好 issue）：你隔离出了底层 bug，并提供了一个作为 Github 仓库的最小复现。Antfu 写了一篇很棒的文章介绍 为什么需要复现 。
-
DECENT ISSUE（尚可的 issue）：你正确地陈述了你的问题。分享最初产生该问题的代码。同时包含相关的配置文件以及你使用的包版本。
最后同样重要的是，请遵循 Github markdown 语法指南 正确地格式化每一个代码块。
-
POOR ISSUE（糟糕的 issue）：你把问题一股脑地丢出来，指望对方来问相关的问题并帮助你。这类 issue 会在没有任何解释的情况下被自动关闭。
展开讨论
你经常想要讨论某个话题，或者分享一些想法。在这种情况下，请在讨论论坛的 💡Ideas 分类下创建一个讨论。
教导他人
教导他人是向任何社区做贡献并赢得认可的最佳方式之一。
你可以使用我们讨论论坛上的 📚 Cookbooks 分类来与他人分享文章。cookbooks 板块并非严格审核，唯一的例外是所分享的知识应与项目相关。
创建 pull request
在投入大量时间和精力编写代码之后，你的 pull request 却被拒绝，这绝不是一个好的体验。因此，我们强烈建议你在自己开始任何新工作之前，先 发起一个讨论 。
只需发起一个讨论并说明你打算贡献什么？
-
你是在尝试创建一个 PR 来修复 bug：一旦 bug 被确认，修复 bug 的 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。它包揽了创建发布并发布到 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 钩子系统 |
命令
| 命令 | 描述 |
|---|---|
npm run test | 使用 ts-node 运行项目测试 |
npm run compile | 将 TypeScript 项目编译为 JavaScript。编译输出写入 build 目录中 |
npm run release | 使用 np 启动发布流程 |
npm run lint | 使用 ESlint 为代码库执行 lint |
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 的 自动生成发布说明 功能，它会在发布说明中添加对贡献者个人资料的引用。