docs: enhance Contribution Guide and Migration Guide

[cheton]

Demo

https://trendmicro-frontend.github.io/tonic-ui-demo/react/pr-883

---

PR Type

Documentation, Enhancement

---

Description

• Updated the v1 to v2 migration guide to include detailed component updates and deprecations.
• Changed section titles for better clarity and organization.
• Added specific code examples and recommended configurations for migrating deprecated components.
• Provided new import paths and steps for updating dependencies.

---

Changes walkthrough 📝

	Relevant files
Documentation	index.page.mdx Update v1 to v2 migration guide with component updates      packages/react-docs/pages/getting-started/migration-v1-to-v2/index.page.mdx Updated section titles for better clarity. Added detailed component deprecation notices and migration steps. Provided specific code examples for migrating deprecated components. Included new recommended configurations and import paths. +101/-13

---

💡 PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[codesandbox[bot]]

Review or Edit in CodeSandbox

Open the branch in Web Editor • VS Code • Insiders
Open Preview

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: d4c7a032d56ba3f9cfa1a02cfafa6ba85bc37e05

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[codiumai-pr-agent-free[bot]]

PR Reviewer Guide 🔍

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Key issues to review None

[codiumai-pr-agent-free[bot]]

PR Code Suggestions ✨

Category	Suggestion	Score
Performance	Define the icon components outside of the route objects to prevent unnecessary re-renders ___ **The icon property in the new sections uses an inline function to render the ListOpenIcon. This can lead to unnecessary re-renders. Consider defining the icon component outside of the route object to avoid this.** [packages/react-docs/config/sidebar-routes.js [44-66]](https://github.com/trendmicro-frontend/tonic-ui/pull/883/files#diff-60ec0437285b17a02f107ee8ed56a48e098bfebde4f8975790fb65d4055c23d8R44-R66) ```diff -icon: (props) => ( - -), +const ContributionGuideIcon = (props) => ; +const MigrationGuideIcon = (props) => ; +// In the routes array +icon: ContributionGuideIcon, +// ... +icon: MigrationGuideIcon, + ``` Suggestion importance[1-10]: 8 Why: The suggestion correctly identifies a performance issue with inline function definitions for icons, which can cause unnecessary re-renders. Implementing this change would improve the performance.	8
Best practice	✅ Move the "Major Updates and Breaking Changes" section to the top for better visibility ___ Suggestion Impact: The "Major Updates and Breaking Changes" section was moved to the top of the document, making it more prominent as suggested. code diff: ```diff +# Migrating From v1 to v2 + +⚠️ This guide outlines the necessary steps to migrate from Tonic UI v1 to v2. Please review the breaking changes and assess the compatibility with your current setup before proceeding with the upgrade. + +## Major Updates and Breaking Changes + +This section highlights the major updates and breaking changes in Tonic UI v2. ``` ___ **The section "Major Updates and Breaking Changes" should be more prominent. Consider moving it to the top of the document to ensure users see it first.** [packages/react-docs/pages/migration-guide/migrating-from-v1-to-v2.page.mdx [11-16]](https://github.com/trendmicro-frontend/tonic-ui/pull/883/files#diff-57dab2e256c8496dcbd4a148689569f6b144a7b7215abdc66bf145f3dcde61caR11-R16) ```diff +# Migrating From v1 to v2 + +⚠️ This guide outlines the necessary steps to migrate from Tonic UI v1 to v2. Please review the breaking changes and assess the compatibility with your current setup before proceeding with the upgrade. + ## Major Updates and Breaking Changes This section highlights the major updates and breaking changes in Tonic UI v2. ``` - [ ] **Apply this suggestion** Suggestion importance[1-10]: 6 Why: The suggestion is valid as it improves the document structure by making important information about breaking changes more visible. However, the existing placement is not incorrect, so this is a moderate improvement.	6
Enhancement	Simplify the App component by using an arrow function with implicit return ___ **The `App` component can be simplified by using an arrow function with implicit return.** [packages/react-docs/pages/contribution-guide/react-components-part-1-example.js [4-6]](https://github.com/trendmicro-frontend/tonic-ui/pull/883/files#diff-0b03141a92c6dffc5b115baca96d3d1a4b98b0895ed33d99e31df88616ab5ad1R4-R6) ```diff -const App = () => ( - This is Code component -); +const App = () => This is Code component; ``` - [ ] **Apply this suggestion** Suggestion importance[1-10]: 5 Why: The suggestion correctly identifies a simplification in the code, but the improvement is minor as it only changes the syntax without affecting functionality or performance.	5

[codesandbox-ci[bot]]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

[trendmicro-frontend-bot]

Tonic UI Demo

• 2024-07-04 13:56:36 +0000 The PR #883 (7266c32b333c8a77bf8797f735f8f381c9845155) has been deployed to https://trendmicro-frontend.github.io/tonic-ui-demo/react/pr-883/

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Project coverage is 74.88%. Comparing base (474fe55) to head (7266c32).

Additional details and impacted files

```diff @@ Coverage Diff @@ ## v2 #883 +/- ## ========================================== + Coverage 74.82% 74.88% +0.06% ========================================== Files 375 375 Lines 6140 6140 ========================================== + Hits 4594 4598 +4 + Misses 1546 1542 -4 ``` | [Flag](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | Coverage Δ | | |---|---|---| | [codemod](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `74.28% <ø> (ø)` | | | [react](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `72.49% <ø> (+0.07%)` | :arrow_up: | | [react-base](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `100.00% <ø> (ø)` | | | [react-hooks](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `87.59% <ø> (ø)` | | | [styled-system](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `93.42% <ø> (ø)` | | | [theme](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `100.00% <ø> (ø)` | | | [utils](https://app.codecov.io/gh/trendmicro-frontend/tonic-ui/pull/883/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend) | `89.14% <ø> (ø)` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=trendmicro-frontend#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

[cheton]

/help

[codiumai-pr-agent-free[bot]]

PR Agent Walkthrough 🤖

Welcome to the PR Agent, an AI-powered tool for automated pull request analysis, feedback, suggestions and more.

Here is a list of tools you can use to interact with the PR Agent:

Tool	Description	Trigger Interactively :gem:
[DESCRIBE](https://pr-agent-docs.codium.ai/tools/describe/)	Generates PR description - title, type, summary, code walkthrough and labels	- [ ] Run
[REVIEW](https://pr-agent-docs.codium.ai/tools/review/)	Adjustable feedback about the PR, possible issues, security concerns, review effort and more	- [ ] Run
[IMPROVE](https://pr-agent-docs.codium.ai/tools/improve/)	Code suggestions for improving the PR	- [ ] Run
[UPDATE CHANGELOG](https://pr-agent-docs.codium.ai/tools/update_changelog/)	Automatically updates the changelog	- [ ] Run
[ADD DOCS](https://pr-agent-docs.codium.ai/tools/documentation/) 💎	Generates documentation to methods/functions/classes that changed in the PR	- [ ] Run
[TEST](https://pr-agent-docs.codium.ai/tools/test/) 💎	Generates unit tests for a specific component, based on the PR code change	- [ ] Run
[IMPROVE COMPONENT](https://pr-agent-docs.codium.ai/tools/improve_component/) 💎	Code suggestions for a specific component that changed in the PR	- [ ] Run
[ANALYZE](https://pr-agent-docs.codium.ai/tools/analyze/) 💎	Identifies code components that changed in the PR, and enables to interactively generate tests, docs, and code suggestions for each component	- [ ] Run
[ASK](https://pr-agent-docs.codium.ai/tools/ask/)	Answering free-text questions about the PR	[*]
[GENERATE CUSTOM LABELS](https://pr-agent-docs.codium.ai/tools/custom_labels/) 💎	Generates custom labels for the PR, based on specific guidelines defined by the user	[*]
[CI FEEDBACK](https://pr-agent-docs.codium.ai/tools/ci_feedback/) 💎	Generates feedback and analysis for a failed CI job	[*]
[CUSTOM PROMPT](https://pr-agent-docs.codium.ai/tools/custom_prompt/) 💎	Generates custom suggestions for improving the PR code, derived only from a specific guidelines prompt defined by the user	[*]
[SIMILAR ISSUE](https://pr-agent-docs.codium.ai/tools/similar_issues/)	Automatically retrieves and presents similar issues	[*]

(1) Note that each tool be triggered automatically when a new PR is opened, or called manually by commenting on a PR.

(2) Tools marked with [*] require additional parameters to be passed. For example, to invoke the /ask tool, you need to comment on a PR: /ask "<question content>". See the relevant documentation for each tool for more details.

[cheton]

/improve

[cheton]

/ask Review the contribution guide and migration guide and offer suggestions if needed

[codiumai-pr-agent-free[bot]]

Ask❓

Review the contribution guide and migration guide and offer suggestions if needed

Answer:

Contribution Guide Review

1. Section Titles and Structure:

   • The change from "Contributing" to "Contribution Guide" is a good move for clarity. It makes the purpose of the section more explicit.

2. Import Paths:

   • The updates to import paths (e.g., import BorderedBox from '../../components/BorderedBox';) are necessary for consistency and correctness. Ensure all paths are updated uniformly across the documentation.

3. Example Code:

   • The addition of the react-components-part-1-example.js file is helpful. It provides a clear, simple example of how to use the Code component.
   • Consider adding more comments within the example to explain each part of the code for beginners.

4. Detailed Steps:

   • The detailed steps for contributing to React components are well-structured. Ensure that each step is as detailed as possible to avoid any confusion for new contributors.

Migration Guide Review

1. Major Updates and Breaking Changes:

   • The reorganization to highlight major updates and breaking changes at the beginning is excellent. It sets the right context for users before diving into specifics.

2. Component Deprecations:

   • The deprecation notices are clear and well-formatted. Ensure that each deprecated component has a corresponding recommended alternative or solution.
   • Example:

     - <Checkbox ref={checkboxRef} />
     + <Checkbox inputRef={checkboxRef} />

3. Component Modifications:

   • The detailed list of component modifications is very useful. Each change is clearly explained, which will help users understand what needs to be updated in their code.
   • Consider adding a summary table at the beginning of this section for quick reference.

4. Code Examples:

   • The code examples provided for each modification are helpful. Ensure that all examples are tested and accurate.
   • Example:

     - <Switch ref={switchRef} />
     + <Switch inputRef={switchRef} />

5. Deprecation Notices:

   • The use of <TextLabel><Flex alignItems="center" columnGap="2x" mb="2x"><AlertIcon /> DEPRECATION NOTICE</Flex></TextLabel> is a nice touch. It visually distinguishes important information.

General Suggestions

1. Consistency:

   • Ensure that the terminology and formatting are consistent throughout the guides. For instance, use the same style for headings, code blocks, and alerts.

2. Navigation:

   • Consider adding a table of contents at the beginning of each guide for easier navigation, especially for long documents.

3. Examples and Use Cases:

   • Where possible, add more real-world examples and use cases. This helps users understand the practical application of the changes.

4. Feedback Loop:

   • Encourage users to provide feedback on the migration process. This can help identify any gaps or areas for improvement in the documentation.

Overall, the updates to the contribution and migration guides are comprehensive and well-structured. With a few additional tweaks and enhancements, they will be even more user-friendly and effective.

[cheton]

/improve