本指南介绍了您可以成为 Quasar 持续开发的一部分的方式。

但在我们开始之前，首先要说明一点。在 Quasar 中进行交互的每个人都应遵守 Quasar 行为准则.

现在我们已经说明了这一点，让我们开始吧！

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

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

Quasar 不是“别人的框架”。许多人对 Quasar 做出了贡献，从单个字符到重大的架构变更或重要的文档 - 所有这一切都是为了让 Quasar 对每个人来说都更好。即使您还没有准备好编写代码或文档，也有很多其他方法可以贡献，从报告问题到测试补丁。

支持帮助

最简单的贡献方式之一就是回答我们拥有的不同问答系统中的问题。通过回答您知道答案的问题，甚至通过提供您的最佳猜测，成为 Quasar 社区的支持者和积极成员。成为这类讨论的一部分也可以是一次很好的学习体验。双赢！

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

• GitHub 讨论: 一个询问关于 Quasar 及其生态系统的问题并获得答案的地方。它也是与他人分享您的知识和经验的好地方。您也可以用它来分享您的想法和功能请求。
• Discord 服务器: Quasar 开发人员实时见面聊天的地方。您可以提出问题、分享您的知识并帮助他人。您也可以在那里发布招聘信息或寻找工作。

分享（和构建）您的经验

除了在论坛和聊天中回答问题和分享资源之外，还有其他一些不那么明显的方式可以分享和扩展您的知识

• 开发学习材料。常言道，最好的学习方法就是教学。如果您正在使用 Quasar 做一些有趣的事情，请通过撰写博文、开发研讨会，甚至发布您在社交媒体上分享的 gist 来增强您的专业知识。
• 分享您的技术栈。向其他人展示哪些技术经过了良好测试，可以与 Quasar 集成。推广您的项目并 填写您最喜欢的基于 Quasar 的技术栈. 务必提及 @Quasarframework 和所有其他相关技术。
• 关注您关心的仓库。这将向您发送有关该存储库中活动的通知，让您了解正在进行的讨论和即将推出的功能。这是积累专业知识的绝佳方式，这样您最终就可以帮助解决问题和拉取请求。

报告问题

• GitHub: 如果您想创建一个错误报告或文档报告，GitHub 问题就是为此而设计的。创建问题时，请确保您选择正确的模板并遵循提供的说明。

如果您在 Quasar 中发现了一个不是安全风险的问题，请在 问题 中搜索，查看它是否已经被回答，甚至在开发分支 (dev) 中修复。

• 主仓库 的问题列表专门用于错误报告和文档报告。不符合要求的问题将立即关闭。

  • 对于简单的初学者问题，您可以在 Quasar Discord 聊天 中获得快速答案。

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

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

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

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

• 您必须清楚地描述重现您遇到的问题的必要步骤。尽管我们非常乐意尽可能帮助我们的用户，但诊断没有明确重现步骤的问题非常耗时，而且根本无法持续进行。

• 仅使用最少的代码来重现意外行为。一个好的错误报告应该隔离表现出意外行为的特定方法，并精确地定义预期如何被违反。您期望该方法或方法做什么，以及观察到的行为有何不同？您越精确地隔离问题，我们就能越快地进行调查。

• 没有明确重现步骤的问题将不会被分流。如果一个标有“bug/0-needs-info”的问题在相当长的一段时间内没有收到问题作者的进一步输入，它将被关闭。

• 如果您的问题已解决但仍处于打开状态，请随时关闭它。如果您自己找到了解决方案，解释您是如何修复它的可能会很有帮助。

• 最重要的是，我们恳求您耐心等待：团队必须在您的请求和其他许多责任之间进行平衡 - 修复其他错误，回答其他问题，新功能，新文档等。问题列表不是付费支持，我们无法保证您的问题能以多快的速度得到解决，尽管我们尽了最大努力。

帮助解决现有问题

作为报告问题之外的下一步，您可以通过提供有关问题的反馈来帮助 Quasar 团队解决现有问题。如果您是 Quasar 开发的新手，这可能是一个很好的入门方法，您将熟悉代码库和流程。

如果您检查 GitHub 问题 中的问题列表，您会发现很多问题需要关注。您能为这些问题做些什么？实际上很多。

验证错误报告

首先，验证错误报告很有帮助。您能在自己的计算机上重现报告的问题吗？如果是，您可以添加一条评论来说明您看到了同样的问题。

如果一个问题非常模糊，您能帮助缩小范围吗？也许您可以提供更多信息来帮助重现错误，或者通过消除演示问题不需要的步骤来提供帮助。

任何能让错误报告更简洁或更容易重现的操作都有助于那些试图编写代码来修复这些错误的人 - 无论您最终是否自己编写代码。

测试补丁

您还可以通过检查通过 GitHub 提交给 Quasar 的拉取请求来提供帮助。为了应用某人的更改，您需要首先创建一个专门的分支

$ git checkout -b testing_branch

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

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

应用他们的分支后，对其进行测试！以下是一些需要考虑的事情

• 更改是否真的有效？
• 它有适当的文档覆盖范围吗？其他地方的文档是否应该更新？
• 您喜欢这种实现方式吗？您能想到一种更优雅或更快的实现他们更改一部分的方法吗？

一旦您对拉取请求包含良好的更改感到满意，请在 GitHub 问题上发表评论，表明您批准。您的评论应该表明您喜欢更改，以及您喜欢更改的哪些地方。例如

如果您的评论只是“+1”，那么其他审阅者很可能不会太重视它。表明您花了时间审查拉取请求。

贡献 Quasar 文档

您可以通过使 Quasar 文档更连贯、更一致或更易读，添加缺少的信息，更正事实错误，修复错别字，或将其更新为最新的边缘 Quasar 来帮助改进它。

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

文档最佳实践

随着时间的推移，我们整理了一套我们遵循的规则，遵循这些规则将加快合并过程

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

分叉

导航到 Quasar GitHub 存储库，并按右上角的“分叉”。

克隆分叉的存储库

要能够更改文档，您需要克隆分叉的存储库

$ 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 存储库作为上游

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

2. 获取所有远程分支

$ git fetch upstream

3. 签出您分叉的本地dev分支。

$ git checkout dev
> Switched to branch 'dev'

4. 将 upstream/dev 中的更改合并到您的本地 dev 分支中。这会将您的分叉的 dev 分支与上游存储库同步，而不会丢失您的本地更改。

$ git merge upstream/dev

没有冲突？测试仍然通过？更改对您来说仍然合理？然后继续并打开一个拉取请求，将您的更改应用到主 Quasar 存储库中的 dev 分支。

发出拉取请求

导航到您刚刚推送到（例如 https://github.com/your-user-name/quasar）的存储库，然后单击左上角面板中显示的“新建拉取请求”。

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

写你的故事

我们一直在寻找关于您如何使用 Quasar 或您在 Quasar 中获得的绝佳体验的精彩文章。如果您撰写文章，我们将在我们的 Medium 出版物渠道上发布它，我们还将确保您的文章在我们的社交媒体中得到应有的关注。如果您有兴趣，请联系 blog(at)quasar.dev。我们很乐意收到您的来信！

创建新的 Quasar 应用程序扩展

开始为 Quasar 做出贡献的简便方法是将您在项目中创建的代码泛化，并将其发布为 Quasar 应用程序扩展。按照本指南了解如何创建一个新的扩展。

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

贡献 Quasar UI 源代码

与任何项目一样，都有贡献规则。我们的规则写在这里，请仔细阅读。之后，阅读Quasar 行为准则，您将准备好为 Quasar 的核心存储库做出贡献。

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

拉取请求指南

• 从相关分支签出主题分支，例如 dev (Qv2) 或 v1 (Qv1)，然后合并回该分支。

• 不要在提交中签入 dist。

• 在您处理 PR 时进行多个小的提交是可以的 - 我们将在合并之前让 GitHub 自动将其压扁。

• 如果添加新功能

  • 提供有说服力的理由来添加此功能。
  • 理想情况下，您应该首先打开一个建议问题，并在开始工作之前将其标记为绿色。否则，您可能会在某件事上花费大量时间，而这件事最终可能根本不会被接受，或者不会以您期望的方式被接受。

• 如果修复错误

  • 如果您正在解决特定问题，请在您的 PR 标题中添加 (fix: #xxxx[,#xxx]) (#xxxx 是问题 ID) 以获得更好的发布日志，例如 fix: update entities encoding/decoding (fix #3899)。
  • 请在 PR 中提供有关该错误的详细描述。优先提供现场演示。

开发设置

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

克隆存储库后，运行

$ pnpm i

常用的 NPM 脚本

# Start dev server with a demo app. This app has Quasar source code linked directly so any change will trigger HMR (Hot Module Reload) on the dev server.
# There's a section for each feature where tests are made.
$ pnpm dev

# build all dist files, including npm packages
$ pnpm build
# build only js dist files
$ pnpm build js
# build only type related files
$ pnpm build js types
# build only css dist files
$ pnpm build css

# lint sources
$ pnpm lint

项目结构 (/ui)

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

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

  • components - Quasar Vue 组件的 JS、Sass 和 JSON (API) 文件

  • composables - Quasar 为 Vue 3 Composition API 提供的组合函数

  • 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 框架是一个采用 MIT 许可的开源项目。这些优秀的 赞助者 使得项目的持续开发成为可能。

请阅读我们关于 为什么捐款很重要 的宣言。如果您想成为捐赠者，请查看 Quasar 框架的捐赠活动。

Quasar 贡献者

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