ant-design/docs/blog/contributor-development-maintenance-guide.en-US.md

title	date	author
Contributor development maintenance guide	2023-03-10	kiner-tang

Hi, I'm 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.

{
  "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.

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:

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:

   # 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 caused 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.

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, 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

Epilogue

Hoping that more and more contributors and collaborators will join us to build a more efficient and elegant Ant Design.