跳至主要内容
版本: v8

为 Ionic 做贡献

感谢您对 Ionic Framework 做贡献的兴趣！

贡献礼仪​

请参阅 贡献者行为准则 以了解行为准则信息。

创建问题​

  • 如果您有关于使用该框架的问题，请在 Ionic 论坛 上提问。

  • 您需要清楚地描述重现您遇到的问题所需的步骤。尽管我们非常愿意尽可能地帮助用户，但在没有明确的重现步骤的情况下诊断问题非常耗时，并且不可持续。

  • Ionic 存储库的问题列表专门用于错误报告和功能请求。不符合要求的问题将立即关闭。

  • 没有明确的重现步骤的问题将不会被分类。如果一个问题被标记为“needs: reply”，并且在 14 天内没有收到问题的作者的进一步回复，它将被关闭。

  • 如果您认为自己发现了错误，或者有新的功能想法，请首先确保它还没有被 报告。您可以搜索现有问题，查看是否有类似的问题报告。包括已关闭的问题，因为它们可能已包含解决方案而被关闭。

  • 接下来， 创建一个新问题，详细解释该问题。请在提交问题之前填写填充的问题表单。

创建良好的代码重现​

什么是代码重现？​

代码重现是一个小的应用程序，它用于演示特定问题。代码重现应该包含重现问题所需的最少代码量，并且应该专注于一个问题。

为什么要创建重现？​

您遇到的问题的代码重现有助于我们更好地隔离问题的根源。这是修复任何错误的重要第一步！

如果没有可靠的代码重现，我们不太可能能够解决这个问题，导致它被关闭。换句话说，创建问题的代码重现有助于我们帮助您。

如何创建重现​

  • 使用我们的一个入门模板创建一个新的 Ionic 应用程序。blank 入门应用程序是一个很好的选择。您可以使用以下 Ionic CLI 命令创建一个：ionic start myApp blank
  • 添加重现您遇到的问题所需的最小代码量。不要包含任何不必要的代码。这包括您安装的任何第三方插件。
  • 在 GitHub 上发布该应用程序，并在 创建问题 时包含指向它的链接。
  • 务必包含重现问题的步骤。这些步骤应该清晰易懂。

创建重现的好处​

  • 使用最新版本的 Ionic：通过创建一个新的 Ionic 应用程序，您可以确保您是在测试最新版本的框架。有时您遇到的问题在框架的较新版本中已经得到解决！
  • 最小的表面积：通过删除重现问题所需的代码，可以更容易地识别问题的原因。
  • 不需要秘密代码：创建问题的最小重现可以防止您发布项目中使用的任何专有代码。
  • 获得帮助修复问题：如果我们能够可靠地重现问题，我们很有可能能够解决它。

创建拉取请求​

  • 感谢您抽出时间做出贡献！在提交拉取请求之前，我们要求您请 创建一个问题，解释错误或功能请求，并让我们知道您计划为此创建拉取请求。如果问题已经存在，请在该问题上发表评论，让我们知道您想为此提交拉取请求。这有助于我们跟踪拉取请求，并确保没有重复的工作。

  • 正在寻找需要修复的问题？请务必查看我们的 需要帮助 标签的问题！

设置​

  1. 下载安装程序 用于 Node.js 的 LTS 版本。这是安装 npm 的最佳方式。
  2. 分叉 Ionic 存储库。
  3. 克隆您的分叉。
  4. 从 master 创建一个新的分支来进行您的更改。
  5. 导航到您要修改的包的目录（core、angular 等）。
  6. 运行 npm install 以安装该包的依赖项。
  7. 按照下面特定包的步骤操作。

核心​

修改组件​

  1. 在 /core/src/components/ 中找到要修改的组件。
  2. 查看 Stencil 文档 和其他组件，了解这些组件的实现。
  3. 对组件进行更改。如果更改过于复杂或超出常規，请添加注释，以便我们理解这些更改。
  4. 预览您的更改 在本地。
  5. 修改文档 如果需要。
  6. 运行 lint 在该目录上，并确保没有错误。
  7. 构建项目.
  8. 构建完成后，提交更改。请在每次提交时遵循 提交消息格式。
  9. 提交拉取请求 您更改的内容。

预览更改​

  1. 从 core 目录中运行 npm start。
  2. 浏览器应该在 https://127.0.0.1:3333/ 中打开。
  3. 从此处，导航到其中一个组件的测试，以预览您的更改。
  4. 如果不存在显示您更改的测试，请 添加新测试或更新现有测试。
  5. 要在 RTL 模式下测试，在您进入所需组件的测试后，在 URL 末尾添加 ?rtl=true；例如：https://127.0.0.1:3333/src/components/alert/test/basic?rtl=true。

Lint 变更​

  1. 运行 npm run lint 来 lint TypeScript 和 Sass。
  2. 如果有 lint 错误，运行 npm run lint.fix 自动修复任何错误。重复步骤 1 以确保错误已修复，如果未修复，请手动修复它们。
  3. 要仅 lint 和修复 TypeScript 错误，请分别运行 npm run lint.ts 和 npm run lint.ts.fix。
  4. 要仅 lint 和修复 Sass 错误，请分别运行 npm run lint.sass 和 npm run lint.sass.fix。

修改文档​

  1. 在组件目录中找到 readme.md 文件。
  2. 修改此文件中的 <!-- Auto Generated Below --> 所在行 **上面** 的文档。
  3. 要更新该行以下的任何自动生成的文档，请在以下位置进行相关更改
  • Usage：更新组件目录的 usage/ 目录中组件的使用示例
  • Properties、Events 或 Methods：更新组件的 TypeScript 文件 (*.tsx)
  • CSS Custom Properties：更新组件的主 Sass 文件 (*.scss)

修改测试​

  1. 在组件目录的 test/ 文件夹中找到要修改的测试。
  2. 如果存在测试，请通过添加示例来修改测试，以重现已修复的问题或添加的功能。
  3. 如果需要新的测试，最简单的方法是复制组件 test/ 目录中的 basic/ 目录，重命名它，然后编辑 index.html 和 e2e.ts 文件中的内容（有关此文件的更多信息，请参见 截图测试）。
  4. preview/ 目录在文档中用作演示。只有在测试中存在错误或 API 发生了未在测试中更新的更改时，才更新此测试。
截图测试​
  1. 如果测试存在于截图中，则测试目录中将有一个名为 e2e.ts 的文件。
  2. 可以通过包含此文件并添加一个或多个包含对 page.compareScreenshot() 的调用的 test() 调用来添加截图测试。有关示例，请参见 Stencil 端到端测试 和 core/ 中的现有测试。
  3. 重要：每个 test() 应该只有一个截图 (page.compareScreenshot()) 调用 **或** 它应该在每个测试结束时检查期望。如果存在不匹配，则测试将失败，这将阻止其余测试运行，例如，如果第一个截图失败，则其余截图调用将不会被调用，除非 它们在单独的测试中或所有期望都在最后被调用。
  4. 要在本地运行截图，请使用以下命令：npm run test.screenshot。
    • 要为特定测试运行截图，请传递测试路径或要搜索的字符串。
    • 例如，运行所有 alert 测试：npm run test.screenshot alert。
    • 或者，运行基本 alert 测试：npm run test.screenshot src/components/alert/test/basic/e2e.ts。

构建变更​

  1. 完成所有更改并更新文档后，在 core 目录中运行 npm run build。如果需要，这将把您的更改添加到任何自动生成的的文件。
  2. 查看更改，如果一切看起来都正确，请 提交 更改。
  3. 确保构建完成后再提交。如果您对文档、属性、方法或需要更新生成文件的任何其他内容进行了更改，则需要提交此更改。
  4. 更改推送后，发布分支并 创建拉取请求。

提交拉取请求​

  1. 创建一个新的拉取请求，将 master 分支作为 base。您可能需要点击 compare across forks 才能找到您的更改。
  2. 有关更多信息，请参见 从分叉创建拉取请求 GitHub 帮助文章。
  3. 请尽您所能填写提供的拉取请求模板，并包含任何相关问题。

提交消息指南​

我们对 Git 提交消息的格式有非常严格的规则。这将产生易于理解的消息，在浏览项目历史记录时易于遵循。我们还使用 Git 提交消息来生成我们的 变更日志。我们的格式与 Angular 的 提交消息指南 非常相似。

提交消息格式​

我们遵循 常规提交规范。提交消息由 **标题**、**正文** 和 **脚注** 组成。标题包含 **类型**、**范围** 和 **主题**

<type>(<scope>): <subject>
<BLANK LINE>
<body>
<BLANK LINE>
<footer>

**标题** 是必需的，**范围** 是可选的。

还原​

如果提交还原了先前的提交，则它应该以 revert: 开头，后跟已还原提交的标题。在正文中，它应该说明：This reverts commit <hash>.，其中哈希是正在还原的提交的 SHA。

类型​

如果前缀是 feat、fix 或 perf，它将出现在变更日志中。但是，如果存在任何 BREAKING CHANGE，提交将始终出现在变更日志中。

必须是以下之一

  • feat：一项新功能
  • fix：一个错误修复
  • docs：仅文档更改
  • style：不影响代码含义的更改（空白、格式、缺少分号等）
  • refactor：既不修复错误也不添加功能的代码更改
  • perf：改进性能的代码更改
  • test：添加缺少的测试
  • chore：对构建过程或辅助工具和库（如文档生成）的更改

范围​

范围可以是任何指定提交更改位置的内容。通常它将引用一个组件，但它也可以引用一个实用程序。例如 action-sheet、button、css、menu、nav 等。如果您对同一组件进行了多次提交，请保持此组件的命名一致。例如，如果您对导航进行了更改，并且第一个提交是 fix(nav)，则应继续使用 nav 来进行与导航相关的任何其他提交。一般来说，如果您修改了组件，请使用文件夹的名称。

主题​

主题包含对更改的简洁描述

  • 使用祈使句，现在时：“change” 而不是 “changed” 或 “changes”
  • 不要将首字母大写
  • 不要在末尾放置句号 .
  • 提交消息的整个长度不得超过 50 个字符
  • 描述提交做了什么，而不是它与什么问题相关或修复什么问题
  • 简洁，但描述性 - 通过阅读主题，我们应该对提交做了什么有一个很好的理解

正文​

与 **主题** 一样，使用祈使句，现在时：“change” 而不是 “changed” 或 “changes”。正文应包含更改的动机，并将其与以前的行为进行对比。

脚注应包含有关 **破坏性变更** 的任何信息，也是引用此提交 **关闭** 的 GitHub 问题的场所。

破坏性变更 应该以 BREAKING CHANGE: 开始，后面跟着一个空格或两个新行。提交消息的其余部分将用于此。

示例​

不会出现在生成的变更日志中

docs(changelog): update steps to update

出现在“Features” 标题下，toast 子标题下

feat(toast): add 'buttons' property

出现在“Bug Fixes” 标题下，skeleton-text 子标题下，并带有指向问题 #28 的链接

fix(skeleton-text): use proper color when animated

closes #28

出现在“Performance Improvements” 标题下，以及“Breaking Changes” 标题下，其中包含破坏性更改的解释

perf(css): remove all css utility attributes

BREAKING CHANGE: The CSS utility attributes have been removed. Use CSS classes instead.

出现在“Breaking Changes” 标题下，其中包含破坏性更改的解释

refactor(animations): update to new animation system

BREAKING CHANGE:

Removes the old animation system to use the new Ionic animations.

如果以下提交和提交 667ecc1 位于同一个发布版中，它们不会出现在变更日志中。如果不是，则还原提交将出现在“Reverts” 标题下。

revert: feat(skeleton-text): add animated property

This reverts commit 667ecc1654a317a13331b17617d973392f415f02.

许可​

通过将您的代码贡献到 ionic-team/ionic GitHub 存储库，您同意在 MIT 许可下许可您的贡献。

内容

编辑此页面