Browse Source
* docs: update blog * docs: update docs * docs: update docs * docs: update blog * docs: update docs * docs: update docs * docs: update docs * docs: update docs * docs: update docs * feat: update doc * docs: update docs * Update docs/blog/contributor-development-maintenance-guide.zh-CN.md Co-authored-by: afc163 <afc163@gmail.com> * docs: update docs * feat: update doc * Update docs/blog/contributor-development-maintenance-guide.zh-CN.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.zh-CN.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * docs: update docs * docs: update docs * docs: update docs * docs: update docs * docs: update docs * docs: update docs * docs: update docs * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * docs: update docs * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * docs: update docs * docs: update docs * Update docs/blog/contributor-development-maintenance-guide.en-US.md Co-authored-by: MadCcc <1075746765@qq.com> * docs: update docs * docs: update docs --------- Co-authored-by: afc163 <afc163@gmail.com> Co-authored-by: MadCcc <1075746765@qq.com>pull/41205/head
kiner-tang(文辉)
2 years ago
committed by
GitHub
GitHub
4 changed files with 314 additions and 0 deletions
@ -0,0 +1,153 @@ |
|||
--- |
|||
title: Contributor development maintenance guide |
|||
date: 2023-03-10 |
|||
author: kiner-tang |
|||
--- |
|||
|
|||
Hi, I'm [kiner-tang](https://github.com/kiner-tang) who is a heavy user of Ant Design. As the same reason, I come up to be a contributor for fixing bug and some features. Finally, it's my honer to become a member of Ant Design Collaborator. |
|||
|
|||
During the journey from user to contributor, and then from contributor to collaborator, I also encountered many problems. I would like to share my experience with the problem I meet. Hope it can help you to join the Ant Design community. |
|||
|
|||
## Some frequently asked Questions |
|||
|
|||
### About dependent version |
|||
|
|||
There are various of package mangers, such as npm, yarn, or pnpm, providing version-locking solutions to avoid version-inconsistencies issue.However, in Ant Design projects, many functions depend on the original components in the `react-component` repository. We expect that when we encounter some bugs, after the `react-component` fixes and releases the patch version, Instead of manually upgrading the version in the Ant Design project, we can install the latest patch installation package only by reinstalling the dependencies. At this point, the version-lock file provided by the package manager is the main obstacle to automatic updates, because once the version-lock file is available, reinstalling the dependency will also install the version specified by the lock file and cannot be upgraded to the patch version. |
|||
|
|||
Based on the above reasons, we adopt the following methods: |
|||
|
|||
1. Add `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` and other version lock files to `.gitignore` without version tracking. |
|||
|
|||
2. In `package.json`, for the dependencies that we want to update when there is a new patch version, we use `~` description version number to allow patch version update. |
|||
|
|||
```json |
|||
{ |
|||
"dependencies": { |
|||
"rc-cascader": "~3.9.0" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
For the difference between `^` and `~` in the version description of package.json, see [What's the difference between tilde(~) and caret(^) in package.json](https://stackoverflow.com/questions/22343224/whats-the-difference-between-tilde-and-caret-in-package-json). |
|||
|
|||
Thus, when our dependency such as rc-cascader fixes a bug and releases a patch version such as: `3.9.1`, then the user's latest installed version is `3.9.1`. For the maintainer of Ant Design, we only need to execute the following command: |
|||
|
|||
```bash |
|||
git clean -fdx |
|||
npm i |
|||
``` |
|||
|
|||
### Snapshot update problem |
|||
|
|||
In Ant Design, we use Jest for unit test. Many first-time contributors of Ant Design may be confused that CI failed after opening a pull request in which they just modify the text in a demo. This is caused by the snapshot diff test. |
|||
|
|||
In most libraries, idempotence is emphasized. With one method and same parameters, the result should be the same no matter how many times it is executed. In Ant Design, the main use of snapshot test is to verify the idempotence of demos, in order to ensure the stability and certainty of components. Actually, snapshot test is simple. By comparing HTML string generated by each demo in different runnings, we could get which one is broken in PR. |
|||
|
|||
Back to the topic, what should we do if we find snapshot test failed after changing a demo? |
|||
|
|||
1. First, we need to check the snapshot diff to see whether it is the expected change. If there is only the text you modified in demo differs from the origin one, we just need to run the following command to update the snapshot: |
|||
|
|||
```bash |
|||
# Run the test command to update snapshot |
|||
npm run test -u |
|||
``` |
|||
|
|||
2. However, we should find what's going wrong if the diff of snapshot is not only cause by your modification this time. For example, you only modified the text, but found that classnames in snapshots have changed, which obviously does not meet expectations. |
|||
|
|||
The common causes are as follows: |
|||
|
|||
- Local dependency is out of date. This may happen when you pull the latest code, but did not update the local dependency. Deleting `lock` file, `node_modules`, and then reinstalling dependencies could solve this problem. |
|||
|
|||
solution is as simple as deleting the lock file、node_modules and reinstall dependencies. |
|||
|
|||
- Your code not synchronizing baseline code can also result in inconsistent snapshot comparisons. The solution is as simple as pulling the baseline code locally and then rebase your code to the baseline code. |
|||
|
|||
- You may have locally changed the source code not only in demos, which would cause unexpected change. You need to go through your change carefully. |
|||
|
|||
### rc-x Library dependencies |
|||
|
|||
In Ant Design, most components are an upper encapsulation of a component based on `react-component`. Therefore, if we find a problem of `@rc-component/xxx` or `rc-xxx` component when troubleshooting, we need to open PR on those repositories to fix it. After coding, we need to verify that the problem in Ant Design is resolved, in which case we can link the project to Ant Design for verification. For example: |
|||
|
|||
Run `npm link` in the repo you are working on.  |
|||
|
|||
Run `npm link "Project name"` in Ant Design |
|||
|
|||
 |
|||
|
|||
Once we have verified, we can open PR to the repo. Noted that link may cause exceptions when running the test command. Therefore, we need to run the following commands locally to delete the package from link. |
|||
|
|||
```bash |
|||
npm unlink "rc-field-form" --no-save |
|||
npm i |
|||
``` |
|||
|
|||
When the PR is finally merged, usually the maintainers will release a version. If the patch version is released, you only need to install and verify it in Ant Design. But if the minor version is released, you need to upgrade it in Ant Design. After local verification, a separate PR to Ant Design could be opened for bugfix. |
|||
|
|||
### Deprecation |
|||
|
|||
In a large project, if you want to remove an property or a method, it is actually very troublesome. Since your project may already have a lot of items in use, other projects depend on it may get broken. But as the project iterated, we will encounter more and more problems which solutions long time ago may no longer fit. Then, we need to adopt a soft, less radical way to remove it, leaving enough time for users to modify. |
|||
|
|||
In Ant Design, we adopt a **five-step strategic** to deprecate property or method: |
|||
|
|||
1. **Add deprecated tag to the property** |
|||
|
|||
 |
|||
|
|||
After adding the above deprecated tag, we can see warning when using this property: |
|||
|
|||
 |
|||
|
|||
2. **Add console warnings** |
|||
|
|||
 |
|||
|
|||
It is important that after adding console warnings, we need to add a test case to test whether the warnings will be displayed when the deprecated properties are used. |
|||
|
|||
 |
|||
|
|||
3. **Update document**: The above two steps are mainly to warn developers in the editor and browser. Next, we need to update the related document. Generally speaking, if we have a property deprecated, it means that it is not recommended for users to use. So we need to remove the related document and add the description of the new property at the mean time. If it cannot be deleted due to special circumstances, please specify the version this property is supported and the alternative scheme in the remarks column. |
|||
|
|||
4. **Compatibility between old and new**: Now that we're done with the above tips, it's important to make sure that the new property and the deprecated one both works until the deprecated one is removed. That is to say, we must have the deprecated property work normally. We should not apply any changes in addition to the warning. |
|||
|
|||
 |
|||
|
|||
We can do something like this to make sure that the new property takes precedence over the old one. At this point, our property deprecation work is done. |
|||
|
|||
5. **Remove**: After our properties have been deprecated for a certain period of time, usually when the major version is released, we can remove the them. We also need to delete comments, warnings, test cases, and documents that were related the property. At this point our property removal work is done. |
|||
|
|||
## Take it to the next level |
|||
|
|||
After contributing for some time, we believe you have gained a deeper understanding of Ant Design's overall development process and project architecture. At this point, you may want to take on more tasks and contribute more to the open source community. Then, you can apply to be a Collaborator at Ant Design by commenting on the link below for more active contributors. [Add Collaborator permission for some active contributors](https://github.com/ant-design/ant-design/issues/3222), The Collaborators will then start the voting process, and after passing the voting, they will invite you to officially become a Collaborator at Ant Design. |
|||
|
|||
After you become a newly appointed Ant Design collaborator, you will be assigned some additional rights, such as: |
|||
|
|||
- Tag the issue |
|||
- Close the issue |
|||
- Free to create branches under the Ant Design project |
|||
- Free to merge approved PR |
|||
|
|||
- ... |
|||
|
|||
There are some caveats to this. |
|||
|
|||
### Merge PR |
|||
|
|||
It's time to merge PR! Ant Design use both squash merge and commit merge in different case which requires attention. Follow is some introduce about difference: |
|||
|
|||
 |
|||
|
|||
- **Merge pull request**: Merge the current PR into the target branch normally (usually used when branches merge with each other, and commit records will not be merged. Do not use this when merging PRs, otherwise too many redundant commit records will be added to the target branch). |
|||
- **Squash and merge**: Merge the commit record into one and merge it into the target branch (this is usually used for merging PRs). |
|||
- **Rebase and merge**：When you want to adjust the baseline |
|||
|
|||
Merge in Ant Design requires at least one collaborator's approve. Collaborator who approved should ensure PR are fully reviewed and confirm. |
|||
|
|||
### Identify XY Problems |
|||
|
|||
During routine maintenance, some issues can easily reproduce but some others are not. Report sometime get stuck in XY problem which makes requirement or bug question strange to understand. Thus, before resolving the superficial problems, we should dig into the real question. |
|||
|
|||
- [X-Y PROBLEM](https://xyproblem.info/) |
|||
|
|||
## Epilogue |
|||
|
|||
Hoping that more and more contributors and collaborators will join us to build a more efficient and elegant Ant Design. |
|||
@ -0,0 +1,149 @@ |
|||
--- |
|||
title: 贡献者开发维护指南 |
|||
date: 2023-03-10 |
|||
author: kiner-tang |
|||
--- |
|||
|
|||
大家好，我是[kiner-tang(文辉)](https://github.com/kiner-tang)，我个人的工作内容可以说与 Ant Design 密切相关，可以算是 Ant Design 的重度用户了。也正因如此，让我由一个使用者慢慢地向着贡献者 Contributor 迈进，将自己在工作过程中遇到的一些问题和总结出的新特性回馈于社区，并最终很荣幸地成为了 Ant Design 的 Collaborator 中的一员。在从使用者到贡献者，再从贡献者到合作者的旅途中，也遇到了不少的问题，借此机会梳理总结一下，希望能对新加入 Ant Design 社区的贡献者和合作者们有所帮助。 |
|||
|
|||
## 普通常见问题 |
|||
|
|||
### 依赖版本问题 |
|||
|
|||
当前流行的包管理器，无论是 npm、yarn 还是 pnpm，都会提供版本锁定的解决方案，在绝大多数时候，这可以帮我们避免包的版本不一致而导致的一些问题。但在 Ant Design 项目当中，很多功能依赖于 `react-component` 仓库中的原始组件，我们期望当遇到一些 bug 时，在 `react-component` 修复并发布 patch 版本之后，无需在 Ant Design 项目当中手动升级版本，只需重新安装依赖即可安装最新的 patch 版本的安装包。此时，包管理器提供的版本锁定文件就成了阻碍自动更新的元凶，因为一旦有了版本锁定文件，那么，重新安装依赖也会安装锁定文件指定的版本，而无法升级到 patch 版本。 |
|||
|
|||
基于上述原因，我们采用以下方式处理： |
|||
|
|||
1. 将`package-lock.json`、`yarn.lock`、`pnpm-lock.yaml`等版本锁定文件加入到`.gitignore`当中，不纳入版本跟踪。 |
|||
|
|||
2. 在`package.json`当中，针对我们想要在有新的 patch 版本更新的依赖，使用`~`描述版本号，以允许 patch 版本的更新。 |
|||
|
|||
```json |
|||
{ |
|||
"dependencies": { |
|||
"rc-cascader": "~3.9.0" |
|||
} |
|||
} |
|||
``` |
|||
|
|||
关于`package.json`当中版本描述中的`^`和`~`的区别，可参考：[What's the difference between tilde(~) and caret(^) in package.json](https://stackoverflow.com/questions/22343224/whats-the-difference-between-tilde-and-caret-in-package-json) |
|||
|
|||
这样，当我们的依赖，如`rc-cascader`修复了一个 bug 并发布了一个 patch 版本，如：`3.9.1`，那么，用户最新安装的版本就是`3.9.1`，而针对 Ant Design 的维护者，我们只需要执行如下命令： |
|||
|
|||
```bash |
|||
git clean -fdx |
|||
npm i |
|||
``` |
|||
|
|||
### 快照更新问题 |
|||
|
|||
在 Ant Design 当中，我们使用 jest 进行单元测试和覆盖率测试，而很多第一次参与 Ant Design 项目开发的同学可能经常会发现，自己只是修改了某个 demo 中的文字，为啥一推送上去，CI 中的测试任务就失败了呢？这就要从 Ant Design 的**快照检测**说起了。 |
|||
|
|||
在绝大部分工具库中，都是比较强调**幂等性**的概念，意思就是同一个方法，无论执行多少次，只要输入参数是一样的，那么得到的结果也就是一样的。而在 Ant Design 当中，个人认为使用快照检测最大的作用也正是校验我们的 demo 的幂等性，以此确保组件输出的稳定性和确定性。其实快照检测的原理很简单，就是将我们的 demo 生成 html 字符串保存下来，下次在运行测试任务时进行对比，如果发现有差异就说明快照检测失败了。 |
|||
|
|||
回到最初的问题，如果我们改了某个 demo 后发现快照检测失败了，应该如何处理呢？ |
|||
|
|||
1. 首先我们需要检查一下快照对比不一致的地方，看是不是预期的改变，如果只改了文字，而快照对比结果也只有文字是不一样的，那么我们只需要运行以下命令更新快照即可： |
|||
|
|||
```bash |
|||
# 运行测试命令，同时更新快照 |
|||
npm run test -u |
|||
``` |
|||
|
|||
2. 但如果发现快照对比时，发生改变的地方超过了你本次修改的范围，比如你只是更改了文字，但发现快照中的 className 都变了，这明显是不符合预期的，我们就需要排查原因，以下是常见的原因： |
|||
|
|||
- 本地依赖太旧，有可能拉取了最新代码，但没有更新本地依赖，导致依赖包版本过低而出现输出结果不一致。解决方案很简单，删除 lock 文件、node_modules，然后重装依赖即可。 |
|||
- 或者你的代码没有同步基线代码也可能导致快照对比不一致。解决方案也很简单，先将基线代码拉取到本地，然后将你的代码 rebase 到基线代码上即可。 |
|||
- 你本地可能除了改动 demo 之外，还改到了核心代码，导致逻辑发生了改变。你需要仔细检查一下本次更改。 |
|||
|
|||
### rc-x 库依赖 |
|||
|
|||
在 Ant Design 中，大部分的组件都是基于 `react-component` 的组件的一个上层封装，因此，如果有用户报障，我们在排查问题时，如果发现问题出在了 `@rc-component/xxx` 或 `rc-xxx` 组件当中，那么我们就需要往这些组件提 pr 进行修复。在修复之后，我们需要在 Ant Design 项目当中验证修复的结果，那么，我们就可以将该项目 link 到 Ant Design 项目当中去验证。如： |
|||
|
|||
在 rc 项目下执行 `npm link` |
|||
|
|||
 |
|||
|
|||
在 Ant Design 当中执行 `npm link "项目名称"` |
|||
|
|||
 |
|||
|
|||
当我们验证通过后，就可以向 rc 组件提 pr 了。 |
|||
|
|||
需要注意的是，link 可能会导致运行 test 命令时产生异常，因此，我们在本地验证完毕后，需要本地运行以下命令删除 link 过来的包： |
|||
|
|||
```bash |
|||
npm unlink "rc-field-form" --no-save |
|||
npm i |
|||
``` |
|||
|
|||
当最终该 pr 被合并过去之后，通常维护者会发布一个版本，如果发布的是 patch 版本，那么你只需要在 Ant Design 项目当中安装验证一下就好了。但如果发布的是`minor`版本，那么我们还需要在 Ant Design 项目中主动升级一下版本，并在本地验证通过后，单独向 Ant Design 提一个 pr 进行升级修复。 |
|||
|
|||
### 属性过期 |
|||
|
|||
在一个大型项目当中，如果你想要将一个属性或方法废弃掉，其实是非常麻烦的一件事，因为你的项目可能已经有很多项目在使用了，如果直接干掉，那么别人一升级就会控制台满屏飘红，甚至直接跑不起来。但在项目迭代的过程中，我们遇到的场景和问题会越来越多，很久以前的方案可能不再适合了，确实需要废弃掉，那么，我们就需要采用一个柔和的，没那么激进的方式进行废弃，留给用户足够的时间修改。 |
|||
|
|||
在 Ant Design 当中，我们采用**五步走战略**废弃属性或方法： |
|||
|
|||
1. **为属性添加过期标记** |
|||
|
|||
 |
|||
|
|||
当添加了上述过期标记，我们在后续使用这个变量时就可以看到： |
|||
|
|||
 |
|||
|
|||
2. **添加控制台警告** |
|||
|
|||
 |
|||
|
|||
需要注意的是，我们添加了控制台警告后，需要在测试用例当中添加测试用例用于测试使用了过期属性是否会如期展示警告，以确保警告能够正常展示。 |
|||
|
|||
 |
|||
|
|||
3. **文档更新**：上面两步主要是给开发者在编辑器和浏览器预览时的警告提示，接下来，我们还需要更新一下相关的软件文档，通常来说，我们需要过期的属性，就代表不推荐用户使用了，如无特殊情况，我们可以将该属性的描述直接从文档中删除，并同步增加上新的属性的描述。（PS: 如因特殊情况不能删除，可在备注栏说明该属性支持的版本以及替代方案） |
|||
|
|||
4. **新旧兼容**：至此，我们前期的提示工作就算是完成了，接下来还有一件很重要的事情，那就是确保新属性与旧属性和谐相处一段时间，直到旧属性寿终正寝。也就是说，目前我们使用过期的属性也要正常工作，除了警告之外，不能有任何的变化。 |
|||
|
|||
 |
|||
|
|||
我们可以类似这样处理，确保新属性的优先级高于旧属性，如果不存在新属性，才尝试使用旧属性。至此，我们的属性过期工作就算已经完成了。 |
|||
|
|||
5. **彻底删除**：在我们的属性过期一段时间后，通常是主版本号的升级时，我们就可以删除掉废弃的属性，同时也需要删除之前为了废弃该属性添加的注释、警告、测试用例、文档等等。到此我们的属性废弃工作就算是大功告成了 🍻。 |
|||
|
|||
## 更上一层楼 |
|||
|
|||
经过一段时间贡献，相信你已经对 Ant Design 的整体开发流程和项目架构有了更加深入的了解，此时，或许你希望承担更多的任务，为开源社区贡献更多的力量。那么，你可以通过以下链接评论申请成为 Ant Design 的 Collaborator ，获得更多的权限 [Add Collaborator permission for some active contributors](https://github.com/ant-design/ant-design/issues/3222)，Collaborator 们会启动投票流程，投票通过后会邀请你正式成为 Ant Design 的 Collaborator。 |
|||
|
|||
当你成为了 Ant Design 新晋的合作者后，你将会被分配一些额外的权限，如： |
|||
|
|||
- 为 issue 打标签 |
|||
- 自由的关闭 issue |
|||
- 可以在 Ant Design 项目下面自由创建分支 |
|||
- 可以自由的合并已经 Approve 的 PR |
|||
- ... |
|||
|
|||
当然，这其中还是有一些需要注意的。 |
|||
|
|||
### 合并 PR |
|||
|
|||
现在，你已经可以对已经 Approve 的 PR 进行合并了，但是，合并代码也是有讲究的，我们要明白，什么时候该使用`squash`，什么时候不能使用。 |
|||
|
|||
 |
|||
|
|||
- **Merge pull request**：正常将当前 PR 合并到目标分支（通常是分支与分支之间相互合并时使用，不会合并提交记录。合并 PR 时不要用这个，不然会往目标分支添加太多冗余的提交记录） |
|||
- **Squash and merge**：将提交记录合并成一条后合并到目标分支（合并 PR 通常都用这个） |
|||
- **Rebase and merge**：调整基线合并 |
|||
|
|||
我们在合并分支之前，最好与作者确认是否已经完全修改完毕，并确认一下是否经过仔细的审查。并至少有一个维护人员接受（Approve）这一次的 PR 后。确定这次 PR 到底是上述哪一种情况，然后选择相应的方式进行合并。 |
|||
|
|||
### 识别 XY 问题 |
|||
|
|||
我们在社区中与其他用户交流沟通时，那么你就极有可能会遇到**XY 问题**，**XY 问题**严重影响我们排查问题的效率，因此，我们需要对**XY 问题**有一个基础认知和辨别能力，并学会如何避免陷入**XY 问题**的陷阱当中。 |
|||
|
|||
- [高效沟通的拦路虎——XY 问题](https://zhuanlan.zhihu.com/p/612569093) |
|||
- [X-Y PROBLEM](https://coolshell.cn/articles/10804.html) |
|||
|
|||
## 结语 |
|||
|
|||
衷心期望能有越来越多的贡献者和合作者加入，一起共建更加高效优雅的 Ant Design。 |
|||
Loading…
Reference in new issue