本指南介绍了您可以参与 Quasar 持续开发的各种方式。

但在开始之前，有一个重要的前提。所有与 Quasar 互动的人都应遵守 Quasar 行为准则。

好了，了解了这一点，让我们开始吧！

阅读本指南后，您将了解：

• 如何使用 GitHub 报告问题。
• 如何克隆仓库并运行测试套件。
• 如何帮助解决现有问题。
• 如何为 Quasar 文档做贡献。
• 如何创建 Quasar App Extension。
• 如何为 Quasar 源代码做贡献。

Quasar 不是"别人的框架"。许多人为 Quasar 做出了贡献，从一个字符到大规模的架构变更或重要的文档——所有这些都是为了让 Quasar 对每个人都更好。即使您还不想编写代码或文档，您也可以通过报告问题到测试补丁等多种方式做出贡献。

帮助支持

最简单的贡献方式之一是在我们不同的问答系统中回答问题。通过回答您知道答案的问题，甚至提供您的最佳猜测，成为 Quasar 社区中积极且乐于助人的一员。参与这样的讨论也是一种很好的学习体验。这是一种双赢！

以下是我们的讨论/问答场所：

• GitHub Discussions：提问和获取关于 Quasar 及其生态系统答案的地方。这也是分享您的知识和经验的好地方。您还可以用它来分享您的想法和功能需求。
• Discord 服务器：Quasar 开发者实时会面和聊天的地方。您可以提问、分享知识并帮助他人。也可以在那里发布招聘信息或寻找工作机会。

分享（和积累）您的经验

除了在论坛和聊天中回答问题和分享资源外，还有一些不太明显的方式来分享和扩展您的知识：

• 开发学习材料。 常言道，最好的学习方式是教学。如果您正在用 Quasar 做一些有趣的事情，可以通过撰写博客文章、开发工作坊，甚至发布一个在社交媒体上分享的 gist 来巩固您的专业知识。
• 分享您的技术栈。 向他人展示哪些技术经过了充分测试并可以与 Quasar 集成。推广您的项目并填写您最喜欢的基于 Quasar 的技术栈。确保提及 @Quasarframework 和所有其他相关技术。
• 关注您关心的仓库。 这将在该仓库有活动时向您发送通知，让您了解正在进行的讨论和即将推出的功能。这是积累专业知识的绝佳方式，最终您将能够帮助解决问题和审查 pull request。

报告问题

• GitHub：如果您想创建 bug 报告或文档报告，请使用 GitHub issues。确保选择正确的模板并在创建 issue 时遵循给定的说明。

如果您在 Quasar 中发现了一个不涉及安全风险的问题，请先在 GitHub 的 Issues 中搜索，检查它是否已经被回答或甚至已在开发分支（dev）中修复。

• 主仓库的 issue 列表仅用于 bug 报告和文档报告。不符合规范的 issue 将被立即关闭。

  • 对于简单的新手问题，您可以从 Quasar Discord 聊天获得快速解答。

  • 对于更复杂的问题，您可以使用讨论区。提问时请确保提供足够的信息——这样其他人更容易帮助您！

  • 对于功能请求，您可以发起一个新的功能讨论。

• 尝试搜索您的问题，它可能已经被回答或甚至已在开发分支（dev）中修复。

• 检查该问题是否可以在最新稳定版本的 Quasar 中复现。请始终标明您使用的具体版本。

• 必须清楚描述复现您遇到问题的步骤。虽然我们希望尽可能多地帮助用户，但在没有清晰复现步骤的情况下诊断问题是极其耗时且不可持续的。

• 仅使用复现意外行为所需的最少代码。好的 bug 报告应该隔离出表现异常的特定方法，并精确定义期望是如何被违反的。您期望方法做什么，观察到的行为有何不同？您越精确地隔离问题，我们就能越快地调查。

• 没有清晰复现步骤的 issue 将不会被处理。如果一个标记为 “bug/0-needs-info” 的 issue 在相当长时间内没有收到作者的进一步回复，它将被关闭。

• 如果您的问题已解决但 issue 仍然开着，请不要犹豫关闭它。如果您自己找到了解决方案，解释一下您是如何修复的会很有帮助。

• 最重要的是，请您耐心等待：团队必须在您的请求与许多其他职责之间取得平衡——修复其他 bug、回答其他问题、新功能、新文档等。issue 列表不是付费支持，我们无法保证您的问题多快能被解决，尽管我们会尽最大努力。

帮助解决现有问题

在报告问题之外的下一步，您可以通过对现有问题提供反馈来帮助 Quasar 团队解决它们。如果您是 Quasar 开发的新手，这可能是迈出第一步的好方法，您将熟悉代码库和流程。

如果您查看 GitHub Issues 中的问题列表，您会发现很多问题已经需要关注。您能为这些做什么呢？实际上相当多：

验证 Bug 报告

首先，仅仅验证 bug 报告就很有帮助。您能在自己的电脑上复现报告的问题吗？如果可以，您可以在 issue 中添加评论说您也遇到了同样的问题。

如果一个 issue 很模糊，您能帮助将其缩小到更具体的范围吗？也许您可以提供额外信息来帮助复现 bug，或者帮助消除不必要的步骤来演示问题。

任何使 bug 报告更简洁或更容易复现的努力都有助于尝试编写代码修复这些 bug 的人——无论最终是否由您来编写代码。

测试补丁

您还可以通过审查通过 GitHub 提交到 Quasar 的 pull request 来帮助。要应用他人的更改，首先需要创建一个专用分支：

$ git checkout -b testing_branch

然后，您可以使用他们的远程分支来更新您的代码库。例如，假设 GitHub 用户 JohnSmith 已经 fork 并推送到了位于 https://github.com/JohnSmith/quasar 的 “orange” 主题分支。

$ git remote add JohnSmith https://github.com/JohnSmith/quasar.git
$ git pull JohnSmith orange

应用他们的分支后，测试一下！以下是一些需要思考的问题：

• 更改实际上有效吗？
• 它有适当的文档覆盖吗？其他地方的文档是否需要更新？
• 您喜欢这个实现吗？您能想到更优雅或更快的方式来实现他们更改的某个部分吗？

一旦您确认 pull request 包含好的更改，请在 GitHub issue 上发表评论表示您的认可。您的评论应该表明您喜欢这个更改以及您喜欢它的哪些方面。类似于：

如果您的评论只是 “+1”，那么其他审查者可能不会太认真对待。请展示您花时间审查了该 pull request。

为 Quasar 文档做贡献

您可以通过使文档更连贯、一致或可读，添加缺失信息，纠正事实错误，修复拼写错误，或使其与最新的 Quasar 保持同步来帮助改进 Quasar 文档。

对于较大的编辑，请更改 Quasar 源文件（位于 GitHub 上的这里）。

文档最佳实践

随着时间推移，我们整合了一系列规则，遵循它们将加速合并过程：

• 标题大写，参见 How to Use Capitalize My Title。
• 使用现在时态。
• 简洁，避免文本/代码重复。
• 链接到通常被用作主要信息源且更频繁更新的外部资源，如 Mozilla MDN、Vue.js API，而不是很快就会过时的编译教程。
• 在提交 PR 之前进行校对
• 不要重复其他来源的文本，只保留与 Quasar 特定功能相关的内容
• 使用官方名称。例如使用 Firebase 而不是 firebase
• 从 PR 中排除所有草稿和未完成的页面

Fork

导航到 Quasar GitHub 仓库并点击右上角的 “Fork”。

克隆 fork 的仓库

要能够修改文档，您需要克隆 fork 的仓库：

$ git clone https://github.com/your-user-name/quasar.git
$ cd quasar
$ git checkout dev

安装依赖

安装所需的依赖。

$ pnpm i

在本地仓库上运行文档

$ cd docs
$ pnpm dev

文档将基于您本地克隆的仓库运行。

编辑并在本地测试您的更改

提交您的更改

当您对计算机上的更改满意时，需要将更改提交到 Git：

$ git commit -a

这将启动您的编辑器来编写提交信息。完成后，保存并关闭以继续。

更新本地仓库

在您工作期间，master 很可能已经发生了其他更改。获取它们。

1. 添加 Quasar 远程仓库作为 upstream

$ git remote add upstream https://github.com/quasarframework/quasar.git

2. 获取所有远程分支

$ git fetch upstream

3. 检出您 fork 的本地 dev 分支。

$ git checkout dev
> Switched to branch 'dev'

4. 将 upstream/dev 的更改合并到您的本地 dev 分支。这使您 fork 的 dev 分支与上游仓库保持同步，同时不会丢失您的本地更改。

$ git merge upstream/dev

没有冲突？测试仍然通过？更改看起来仍然合理？那么继续前进，打开一个 pull request 将您的更改应用到 Quasar 主仓库的 dev 分支。

提交 Pull Request

导航到您刚推送的仓库（例如 https://github.com/your-user-name/quasar）并点击左上面板中的 “New Pull Request”。

确保包含您引入的更改集。填写一些关于您潜在补丁的详细信息，包括一个有意义的标题。完成后，点击 “Create pull request”。Quasar 核心团队将收到关于您提交的通知。

撰写您的故事

我们一直在寻找关于您如何使用 Quasar 或与 Quasar 相关的精彩体验的优秀文章。如果您写了一篇文章，我们将在我们的 Medium 发布渠道上发布它，我们还会确保您的文章通过我们的社交媒体获得应有的关注。如果您感兴趣，请联系 blog(at)quasar.dev。我们期待收到您的来信！

创建新的 Quasar App Extension

开始为 Quasar 做贡献的一个简单方法是将您在项目中创建的代码泛化并作为 Quasar App Extension 发布。请按照此指南了解如何创建新扩展。

完成后，在 Quasar Awesome 上提交 PR，通过 Quasar 论坛分享您的成果。

为 Quasar UI 源代码做贡献

与任何项目一样，贡献也有规则。我们的规则写在这里，请仔细阅读。之后，阅读 Quasar 行为准则，您就可以准备为 Quasar 的核心仓库做贡献了。

一篇文章查看源代码将帮助您熟悉 Quasar 代码库。

Pull Request 指南

• 从相关分支检出一个主题分支，例如 dev（Qv2）或 v1（Qv1），然后合并回该分支。

• 不要在提交中包含 dist。

• 在处理 PR 时可以有多个小的提交——我们会让 GitHub 在合并前自动压缩它们。

• 如果添加新功能：

  • 提供令人信服的理由来添加此功能。
  • 理想情况下，您应该先开一个建议 issue 并在获得批准后再开始工作。否则，您可能会花费大量时间在最终不被接受或不以您期望的形式被接受的事情上。

• 如果修复 bug：

  • 如果您正在解决特定的 issue，请在 PR 标题中添加 (fix: #xxxx[,#xxx])（#xxxx 是 issue ID）以获得更好的发布日志，例如 fix: update entities encoding/decoding (fix #3899)。
  • 在 PR 中提供 bug 的详细描述。推荐提供在线演示。

开发设置

您需要 Node.js v22+ 版本以及 pnpm。阅读 package.json 并注意您可以使用的脚本。

克隆仓库后运行：

$ pnpm i

常用 NPM 脚本

# 启动带有演示应用的开发服务器。此应用直接链接了 Quasar 源代码，
# 因此任何更改都会在开发服务器上触发 HMR（热模块重载）。
# 每个功能都有一个专门的测试区域。
$ pnpm dev

# 构建所有 dist 文件，包括 npm 包
$ pnpm build
# 仅构建 js dist 文件
$ pnpm build js
# 仅构建类型相关文件
$ pnpm build js types
# 仅构建 css dist 文件
$ pnpm build css

# lint 源代码
$ pnpm lint

项目结构 (/ui)

• build - 包含与构建相关的配置文件。大多数情况下您不需要修改它们。

• src - 包含源代码。代码库使用 ES2015 编写。

  • components - Quasar Vue 组件的 JS、Sass 和 JSON（API）文件

  • composables - Quasar 的 Vue 3 组合式 API composables

  • directives - Quasar 提供的 Vue 指令

  • plugins - Quasar 插件

  • css - Quasar 样式的 Sass 定义和核心代码

  • utils - 框架使用并导出到公共 API 的实用工具

• lang - Quasar 语言包

• icon-set - Quasar 图标集

• dist - 包含用于发布的构建文件（仅在构建后存在）。

• dev - 直接链接 Quasar 源代码的应用，用于测试目的。每个功能/组件都有自己的 *.vue 文件。添加新文件会自动创建路由并将其添加到"主页"列表中（基于文件名）。

Quasar 的开发服务器 (/ui)

运行 pnpm dev 会启动一个使用 HMR（热模块重载）的 Quasar 源代码开发服务器。您可以通过对 /dev 的 *.vue 文件进行必要更改来轻松测试您的更改。

资金贡献

Quasar Framework 是一个 MIT 许可的开源项目。它的持续开发得益于这些出色的支持者的支持。

请阅读我们关于为什么捐赠很重要的声明。如果您想成为捐赠者，请查看 Quasar Framework 的捐赠活动。

Quasar 贡献者

感谢所有已经为 Quasar 做出贡献的人！