做出贡献的 · ionic4中文手册

[TOC] 感谢您对Ionic Framework的贡献！ ## 贡献礼仪 [有关行为](https://github.com/ionic-team/ionic/blob/master/CODE_OF_CONDUCT.md)规则的信息，请参阅“[贡献者行为](https://github.com/ionic-team/ionic/blob/master/CODE_OF_CONDUCT.md)准则”。 ## 创建问题 * 如果您对使用该框架有疑问，请咨询[Ionic Forum](http://forum.ionicframework.com/)或[Ionic Worldwide Slack](http://ionicworldwide.herokuapp.com/)小组。 * 您需要清楚地描述重现所遇问题所需的步骤。尽管我们希望尽可能地帮助我们的用户，但是如果没有明确的复制步骤来诊断问题则非常耗时并且根本无法持续。 * [Ionic](https://github.com/ionic-team/ionic)存储库的问题列表专门用于错误报告和功能请求。不合格的问题将立即关闭。 * 没有明确的重现步骤的问题将不会被分类。如果某个问题标有“需要：回复”，并且超过30天没有收到该问题的作者的进一步回复，则该问题将被关闭。 * 如果您认为自己发现了错误或有新功能，请首先确保尚未[报告错误](https://github.com/ionic-team/ionic/issues?utf8=%E2%9C%93&q=is%3Aissue)。您可以搜索现有问题，以查看是否报告了类似的问题。包括已关闭的问题，因为它可能已通过解决方案关闭。 * 接下来，[创建一个](https://github.com/ionic-team/ionic/issues/new/choose)彻底解释问题[的新](https://github.com/ionic-team/ionic/issues/new/choose)问题。请在提交问题前填写填好的问题表。 ## 创建拉取请求 * 感谢您抽出宝贵时间做出贡献！在提交拉取请求之前，我们要求您[创建一个](https://ionicframework.com/docs/building/contributing#creating-an-issue)解释错误或功能请求[的问题](https://ionicframework.com/docs/building/contributing#creating-an-issue)，并告诉我们您计划为其创建拉取请求。如果问题已经存在，请对此问题发表评论，告知我们您要提交拉取请求。这有助于我们跟踪拉取请求并确保没有重复的工作。 * 正在寻找解决问题的方法？请务必通过[帮助](https://github.com/ionic-team/ionic/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)标签查看我们的问题！ ### 建立 1. [下载](https://nodejs.org/)Node.js的LTS版本[的安装程序](https://nodejs.org/)。这是[安装npm](https://blog.npmjs.org/post/85484771375/how-to-install-npm#_=_)的最佳方法。 2. 叉[Ionic](https://github.com/ionic-team/ionic)存储库。 3. 克隆你的叉子。 4. 从master创建一个新分支以进行更改。 5. 导航到要修改的包的目录（核心，角度等）。 6. 运行`npm install`以安装此程序包的依赖项。 7. 请按照以下特定包的步骤进行操作。 ### 核心 #### 修改组件 1. 找到要在内部修改的组件`/core/src/components/`。 2. 查看[Stencil文档](https://stenciljs.com/docs/introduction/)和其他组件以了解这些组件的实现。 3. 对组件进行更改。如果更改过于复杂或与众不同，请添加注释以便我们了解更改。 4. [在](https://ionicframework.com/docs/building/contributing#preview-changes)本地[预览您的更改](https://ionicframework.com/docs/building/contributing#preview-changes)。 5. [](https://ionicframework.com/docs/building/contributing#modifying-documentation)如果需要，[修改文档](https://ionicframework.com/docs/building/contributing#modifying-documentation)。 6. [](https://ionicframework.com/docs/building/contributing#lint-changes)在目录上[运行lint](https://ionicframework.com/docs/building/contributing#lint-changes)并确保没有错误。 7. [建立项目](https://ionicframework.com/docs/building/contributing#building-changes)。 8. 构建完成后，提交更改。请遵循每次提交的[提交消息格式](https://ionicframework.com/docs/building/contributing#commit-message-format)。 9. [提交](https://ionicframework.com/docs/building/contributing#submit-pull-request)您的更改[的拉取请求](https://ionicframework.com/docs/building/contributing#submit-pull-request)。 #### 预览更改 1. `npm start`从`core`目录中运行。 2. 浏览器应该打开`http://localhost:3333/`。 3. 从这里，导航到组件的其中一个测试以预览您的更改。 4. 如果不存在显示更改的测试，请[添加新测试或更新现有测试](https://ionicframework.com/docs/building/contributing#modifying-tests)。 5. 要在RTL模式下进行测试，一旦进入所需组件的测试，请`?rtl=true`在URL的末尾添加;例如：`http://localhost:3333/src/components/alert/test/basic?rtl=true`。 #### 皮棉变化 1. 运行`npm run lint`lint TypeScript和Sass。 2. 如果存在lint错误，请运行`npm run lint.fix`以自动修复任何错误。重复步骤1以确保已修复错误，如果没有，则手动修复它们。 3. 要仅提示并修复TypeScript错误，请分别运行`npm run lint.ts`和`npm run lint.ts.fix`。 4. 要仅修改和修复Sass错误，分别运行`npm run lint.sass`和`npm run lint.sass.fix`。 #### 修改文档 1. `readme.md`在组件的目录中找到该文件。 2. 修改此文件中所述行**上方**的文档``。 3. 要更新该行下面的任何自动生成的文档，请在以下位置进行相关更改： * `Usage`：更新组件`usage/`目录中组件的用法示例 * `Properties`,,`Events`或`Methods`：更新组件的TypeScript文件（`*.tsx`） * `CSS Custom Properties`：更新组件的主Sass文件（`*.scss`） #### 修改测试 1. 找到要`test/`在组件目录中的文件夹内修改的测试。 2. 如果存在测试，请通过添加示例来修改测试，以重现已修复的问题或添加的功能。 3. 如果需要进行新测试，最简单的方法是`basic/`从组件`test/`目录中复制目录，重命名目录，并编辑`index.html`和`e2e.ts`文件中的内容（有关此文件的更多信息，请参阅[屏幕截图测试](https://ionicframework.com/docs/building/contributing#screenshot-tests)）。 4. 该`preview/`目录在文档中用作演示。如果测试中存在错误或者API在测试中有未更新的更改，则仅更新此测试。 ##### 截图测试 1. 如果测试中存在测试，则会`e2e.ts`在测试目录中指定一个文件。 2. 可以通过包含此文件并添加一个或多个`test()`包含调用的调用来添加屏幕截图测试`page.compareScreenshot()`。有关示例，请参阅[模板端到端测试](https://stenciljs.com/docs/end-to-end-testing)和现有测试`core/`。 3. **重要提示：**每个`test()`应该只有一个screenshot（`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. 完成所有更改并更新文档后`npm run build`，在`core`目录内运行。如有必要，这会将更改添加到任何自动生成的文件中。 2. 查看更改，如果一切正常，则[提交](https://ionicframework.com/docs/building/contributing#commit-message-format)更改。 3. 在提交之前确保构建已完成。如果您对文档，属性，方法或需要更新生成文件的任何其他内容进行了更改，则需要提交。 4. 推送更改后，发布分支并[创建拉取请求](https://ionicframework.com/docs/building/contributing#creating-a-pull-request)。 ### 提交拉取请求 1. [创建一个新的拉取请求](https://github.com/ionic-team/ionic/compare)，`master`分支为`base`。您可能需要单击`compare across forks`以查找更改。 2. 有关详细信息，请参阅[从fork](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)GitHub帮助文章[创建拉取请求](https://help.github.com/articles/creating-a-pull-request-from-a-fork/)。 3. 请尽最大努力填写提供的Pull Request模板，并包括任何相关问题。 ## 提交消息格式我们对如何格式化git提交消息有非常精确的规则。这样可以查看在查看项目历史记录时易于理解的可读消息。我们还使用git commit消息来生成[更改日志](https://github.com/ionic-team/ionic/blob/master/CHANGELOG.md)。（好的，你有我们，它基本上是Angular的提交消息格式）。 `type(scope): subject` #### 类型必须是以下之一： * **专长**：一项新功能 * **修复**：错误修复 * **docs**：文档只会更改 * **style**：不影响代码含义的更改（空格，格式，缺少分号等） * **重构**：代码更改既不修复错误也不添加功能 * **perf**：改进性能的代码更改 * **test**：添加缺失的测试 * **家务**：对构建过程或辅助工具和库（如文档生成）的更改 #### 范围范围可以是指定提交更改位置的任何内容。例如`action-sheet`，`button`，`menu`，`nav`，等等。如果你做了同一组件多次提交，请保留此组件一致的命名。例如，如果您对导航进行了更改并且第一次提交是`fix(nav)`，则应继续使用`nav`与导航相关的任何其他提交。 #### 学科该主题包含对变更的简洁描述： * 使用命令式，现在时：“改变”而非“改变”或“改变” * 不要把第一个字母大写 * 不要`.`在最后放置一段时间 * 提交消息的整个长度不得超过50个字符 * 描述提交的作用，而不是它涉及或修复的问题 * **简短而又具有描述性**\- 我们应该通过阅读主题来很好地理解提交的内容 ## 许可证通过将您的代码提供给ionic团队/ionic GitHub存储库，您同意根据MIT许可证许可您的贡献。