贡献

Nuxt 是一个社区项目 - 我们欢迎各种形式的贡献！❤️

您可以通过多种不同的方式为 Nuxt 生态系统做出贡献。

生态系统

Nuxt 生态系统包括许多不同的项目和组织。

  • nuxt/- Nuxt 框架本身的核心存储库。nuxt/nuxt包含 Nuxt 框架（版本 2 和 3）。
  • nuxt-modules/- 社区贡献和维护的模块和库。将模块迁移到 nuxt-modules 有一个过程。虽然这些模块有独立的维护者，但它们不依赖于某一个人。
  • unjs/- 许多这些库在整个 Nuxt 生态系统中使用。它们被设计成与框架和环境无关的通用库。我们欢迎其他框架和项目贡献和使用。

如何贡献

分类问题并在讨论中提供帮助

查看您想要帮助的项目的议题和讨论。例如，这里是Nuxt 的议题面板。等等讨论帮助其他用户、分享解决方案、创建复现或甚至深入研究一个小错误并分享您的发现都会产生巨大的影响。

创建议题

感谢您花时间创建议题！❤️

  • 报告 bug：请查看我们的指南，了解在提出议题之前需要做的一些事情。
  • 功能请求：检查是否已有涵盖您想法中功能的现有议题或讨论。如果该功能属于 Nuxt 生态系统的其他部分（例如模块），请考虑首先在该处提出功能请求。如果您想法中的功能是通用的或者 API 尚不完全清楚，请考虑在“想法”部分开启讨论，以便首先与社区讨论。

我们将尽力遵循内部议题决策流程图来回复议题。

发送拉取请求

我们始终欢迎拉取请求！❤️

开始之前

在修复 bug 之前，我们建议您检查是否存在描述该 bug 的议题，因为这可能是文档问题，或者可能有一些有用的上下文信息。

如果您正在开发一个功能，我们要求您首先提出功能请求议题，以便与维护者讨论该功能是否需要——以及这些功能的设计。这有助于节省维护者和贡献者的时间，并意味着功能可以更快地发布。该议题应该由框架团队成员确认后，才能在拉取请求中构建该功能。

对于拼写错误修复，建议将多个拼写错误修复批量提交到一个拉取请求中，以保持更清晰的提交历史。

对于 Nuxt 本身较大的更改，我们建议您首先创建一个 Nuxt 模块并在其中实现该功能。这有助于快速进行概念验证。然后您可以以讨论的形式创建一个 RFC。随着用户采纳并收集反馈，它就可以进行完善并添加到 Nuxt 核心，或者继续作为一个独立的模块。

提交约定

我们使用Conventional Commits用于提交消息，这允许自动生成变更日志根据提交。如果您还不熟悉，请通读本指南。

请注意，fix: 和 feat: 用于实际代码更改（可能影响逻辑）。对于拼写错误或文档更改，请改用 docs: 或 chore:。

  • fix: typo -> docs: fix typo

如果您在 monorepo 项目中工作，例如 nuxt/nuxt，请确保在括号中指定提交的主要范围。例如：feat(kit): add 'addMagicStuff' utility。

创建拉取请求

如果您不知道如何发送拉取请求，我们建议您阅读该指南.

发送拉取请求时，请确保您的 PR 标题也遵循提交约定。

如果您的 PR 修复或解决了现有议题，请务必在 PR 描述中提及它们。

单个 PR 中可以有多个提交；您无需为您的更改进行 rebase 或强制 push，因为我们将在合并时使用 Squash and Merge 将提交压缩成一个提交。

我们没有添加任何提交钩子以允许快速提交。但在您提出拉取请求之前，您应该确保所有 lint/测试脚本都通过。

通常，也请确保 PR 中没有**不相关**的更改。例如，如果您的编辑器对您编辑的文件中其他位置的空白或格式进行了任何更改，请撤销这些更改，以便更清楚地显示您的 PR 更改了什么。并且请避免在一个 PR 中包含多个不相关的功能或修复。如果可以分离它们，最好有多个 PR 分别进行审查和合并。通常，一个 PR 应该只做**一件事**。

您提交拉取请求后

您提交拉取请求后，我们将尽力及时进行审查。

如果我们将其分配给维护者，则意味着该维护者将特别注意审查并实施可能需要的任何更改。

如果我们要求对 PR 进行更改，请忽略红色文本！这并不意味着我们认为这是一个糟糕的 PR——这只是一种可以一目了然地轻松了解拉取请求列表状态的方法。

如果我们将 PR 标记为“待处理”，则表示我们在审查 PR 时可能还有其他任务要做——这是一个内部便笺，不一定反映 PR 是一个好主意与否。我们将尽力通过评论解释待处理状态的原因。

我们将尽力遵循我们的 PR 决策流程图来响应和审查拉取请求。

AI 辅助贡献

我们欢迎在贡献 Nuxt 时审慎使用 AI 工具，但要求所有贡献者遵循两个核心原则.

绝不允许大型语言模型 (LLM) 代您发言

  • 所有评论、议题和拉取请求描述都应以您自己的口吻撰写
  • 我们重视清晰的人际交流，而不是完美的语法或拼写
  • 避免复制粘贴不反映您自己理解的 AI 生成摘要

绝不允许大型语言模型 (LLM) 代您思考

  • 随意使用 AI 工具生成代码或探索想法
  • 只提交您完全理解并能解释的贡献
  • 贡献应反映您自己的推理和解决问题的能力

我们的目标是确保质量并保持与真实人员协作和交流的乐趣。如果您对改进 Nuxt 社区的 AI 政策有任何想法，我们非常乐意倾听！❤️

创建模块

如果您使用 Nuxt 构建了一些很酷的东西，为什么不将其提取为模块，以便与他人共享呢？我们已经有许多优秀的模块，但总有更多的空间。

如果您在构建时需要帮助，请随时联系我们。

发起 RFC

我们强烈建议您先创建一个模块，以测试新的大型功能并获得社区的采纳。

如果您已经这样做了，或者不适合创建新模块，那么请首先创建一个新的讨论。确保尽可能清晰地解释您的想法。包括新 API 的代码示例或函数签名。引用现有问题或痛点并提供示例。

如果我们认为这应该是一个 RFC，我们将更改类别为 RFC 并更广泛地进行传播以征求反馈。

一个 RFC 将经历以下阶段

  • rfc: active - 当前开放评论
  • rfc: approved - 经 Nuxt 团队批准
  • rfc: ready to implement - 已创建并分配实现问题的议题
  • rfc: shipped - 已实现
  • rfc: archived - 未批准，但已归档以供将来参考

生态系统内的约定

以下约定在 nuxt/ 组织内是**必需的**，并推荐给生态系统中的其他维护者。

模块约定

模块应遵循Nuxt 模块模板。有关更多信息，请参阅模块指南。

使用核心 unjs/ 库

我们推荐以下在整个生态系统中使用到的库

  • pathe- 通用路径工具（取代 Node 的 path）
  • ufo- URL 解析和连接工具
  • unbuild- 基于 Rollup 的构建系统
  • ... 更多请查看unjs/组织！

使用 ESM 语法并默认 type: module

大多数 Nuxt 生态系统可以直接使用 ESM。通常，我们主张您避免使用 CJS 特有的代码，例如 __dirname 和 require 语句。您可以阅读更多关于 ESM 的信息。

什么是 Corepack

Corepack确保您在运行相应命令时使用正确版本的包管理器。项目可能在其 package.json 中包含 packageManager 字段。

在如下配置的项目下，Corepack 将安装 pnpm 的 v7.5.0 版本（如果您尚未安装）并使用它来运行您的命令。

package.json
{
  "packageManager": "[email protected]"
}

使用 ESLint

我们使用ESLint进行 linting 和格式化，并使用@nuxt/eslint.

IDE 设置

我们建议使用VS Code以及ESLint 扩展。如果您愿意，可以在保存正在编辑的代码时启用自动修复和格式化

settings.json
{
  "editor.codeActionsOnSave": {
    "source.fixAll": "never",
    "source.fixAll.eslint": "explicit"
  }
}

不使用 Prettier

由于 ESLint 已经配置为格式化代码，因此无需使用 Prettier 重复此功能。要格式化代码，您可以运行 yarn lint --fix、pnpm lint --fix 或 bun run lint --fix，或参考ESLint 部分进行 IDE 设置。

如果您的编辑器中安装了 Prettier，我们建议您在项目工作时禁用它，以避免冲突。

包管理器

我们推荐使用 pnpm 作为模块、库和应用程序的包管理器。

启用 Corepack 很重要，以确保您使用的包管理器版本与项目一致。Corepack 内置于新的 Node 版本中，可实现无缝的包管理器集成。

要启用它，请运行

终端
corepack enable

您只需在计算机上安装 Node.js 后执行此操作一次。

文档风格指南

文档是 Nuxt 不可或缺的一部分。我们致力于成为一个直观的框架——其中很大一部分是确保整个生态系统的开发者体验和文档都完美无缺。👌

这里有一些可能有助于改进文档的提示

  • 尽可能避免使用“简单地”、“仅仅”、“显然”等主观词语。
    请记住您的读者可能具有不同的背景和经验。因此，这些词语并不能传达明确的含义，甚至可能造成伤害。
    只需确保函数返回一个 promise。
    确保函数返回一个Promise.
  • 优先使用主动语态.
    Nuxt 将抛出错误。
    Nuxt 将抛出一个错误。
了解如何为文档做出贡献。