8000 docs: add guide for cherry-picking pull requests to another branch by wuhuizuo · Pull Request #3633 · PingCAP-QE/ci · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

docs: add guide for cherry-picking pull requests to another branch #3633

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 6 commits into
base: main
Choose a base branch
from
Open

docs: add guide for cherry-picking pull requests to another branch #3633

wants to merge 6 commits into from

Conversation

wuhuizuo
Copy link
Collaborator
@wuhuizuo wuhuizuo commented Jul 4, 2025 •
edited
Loading

This pull request introduces new documentation for the CI repository, focusing on guides for CI processes, cherry-picking pull requests, and improving the overall organization of the documentation. The changes aim to provide clear instructions and streamline workflows for contributors.

New Documentation Guides

  • docs/guides/CI.md: Added a comprehensive guide to PingCAP's CI system, including instructions on locating pipelines, modifying and testing pipelines, and the workflow for deploying changes from staging to production. Includes a workflow diagram for clarity.
  • docs/guides/cherry-pick-pull-request.md: Introduced a detailed guide on how to cherry-pick pull requests to another branch, covering prerequisites, usage of the helper script, handling conflicts, and best practices.

Improved Documentation Organization

  • docs/guides/README.md: Updated the README to serve as an entry point for the guides section. Added links to available guides, including CI, Docker build instructions, cherry-picking pull requests, and FAQs. Provided recommendations for writing and updating guides.

@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign wuhuizuo for approval. For more information see the Code Review Process.
Please ensure that each of them provides their approval before proceeding.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary:
This pull request adds a comprehensive guide for cherry-picking pull requests to another branch, including a helper script to automate the process and manual instructions for more control. The guide covers prerequisites, basic usage, advanced options, step-by-step process, conflict resolution, troubleshooting, and best practices. The overall quality of the documentation appears to be good, providing detailed instructions and examples for users.

Code Improvements:

  • File: cherry-pick-pull-request.md

    1. Missing Error Handling in Script:
      • Line 71 and onwards.
      • It would be beneficial to include error handling in the script to graceful 8000 ly handle exceptions or failures during the cherry-picking process. This can help users understand what went wrong and how to proceed.

  • Refactoring for Script Readability:

    1. Refactor Long Commands:
      • Consider breaking down long commands in the script (lines 23, 58) for better readability and maintainability. You can split them into multiple lines or create functions to encapsulate complex logic.

Best Practices:

  • File: cherry-pick-pull-request.md

    1. Missing Documentation for Environment Variables:

      • Lines 62-66.
      • Add documentation explaining the purpose and usage of the supported environment variables in the script. This will help users understand how to customize the behavior of the script effectively.

    2. Testing Coverage:

      • While the guide is comprehensive, ensure that the helper script is thoroughly tested for different scenarios, including edge cases and error conditions. Consider adding a section on testing the script.

    3. Consistent Naming Conventions:

      • Check for consistent naming conventions throughout the guide and script. Ensure variables, commands, and options are named consistently for clarity and maintainability.

These improvements will enhance the script's robustness, readability, and user-friendliness, making the cherry-picking process smoother for users.

@ti-chi-bot ti-chi-bot bot added the size/L label Jul 4, 2025
gemini-code-assist[bot]
gemini-code-assist bot reviewed Jul 4, 2025
View reviewed changes
Copy link
Contributor
@gemini-code-assist gemini-code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Summary of Changes

Hello @wuhuizuo, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new comprehensive guide aimed at assisting contributors with the process of cherry-picking pull requests to other branches, particularly for backporting fixes or features. It outlines both an automated approach using a helper script and a detailed manual method, along with best practices and troubleshooting tips.

Highlights

  • New Documentation Guide: A new guide, docs/guides/cherry-pick-pull-request.md, has been added to provide comprehensive instructions on how to cherry-pick pull requests to another branch.
  • Automated Cherry-Picking Workflow: The guide details the use of a helper script (scripts/ops/cherry_pick_pull.sh) that automates much of the cherry-picking process, including handling multiple PRs and supporting advanced options via environment variables.
  • Manual Cherry-Picking Alternative: For users requiring more control, the guide provides a step-by-step alternative for performing manual cherry-picking using standard Git commands.
  • Conflict Resolution and Best Practices: The documentation includes sections on how to handle merge conflicts that may arise during cherry-picking, along with best practices and troubleshooting tips to ensure a smooth workflow.
Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature Command Description
Code Review /gemini review Performs a code review for the current pull request in its current state.
Pull Request Summary /gemini summary Provides a summary of the current pull request in its current state.
Comment @gemini-code-assist Responds in comments when explicitly tagged, both in issue comments and review comments.
Help /gemini help Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

  1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist[bot]
gemini-code-assist bot reviewed Jul 4, 2025
View reviewed changes
Copy link
Contributor
@gemini-code-assist gemini 8000 -code-assist bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request adds a new guide for cherry-picking pull requests, which is a great addition to the documentation. My review focuses on improving the clarity, correctness, and readability of the new guide. I've suggested a few changes to fix a potentially broken link, clarify placeholders, improve a section heading for better understanding, and restructure an instruction to make it less ambiguous. Overall, these are minor changes to an already well-written document.

@ti-chi-bot ti-chi-bot bot added size/XL and removed size/L labels Jul 4, 2025
@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary

This PR introduces documentation updates to the CI repository, including a new guide for cherry-picking pull requests to another branch (cherry-pick-pull-request.md), a detailed CI modification guide (CI.md), and updates to the README.md to incorporate links to these new resources. The approach organizes the information into clear sections and provides actionable, step-by-step instructions. Overall, the documentation is well-structured and comprehensive; however, there are opportunities for improvement in clarity, formatting consistency, and technical accuracy.

Critical Issues

No critical issues were identified in this PR.

Code Improvements

  • File: docs/guides/cherry-pick-pull-request.md

    • Issue: The cherry-pick script's environment variable behavior is described but lacks a warning about potential side effects (e.g., overwriting branches or incorrect upstream configuration).
    • Why it's an issue: Misconfiguration or accidental usage of environment variables like UPSTREAM_REMOTE or FORK_REMOTE could lead to unintended branch updates or PR creation.
    • Suggested Solution: Add a caution note in the "Advanced Options" section and recommend verifying branch states before running the script. 
      **Warning**: Ensure your remote configurations (`UPSTREAM_REMOTE`, `FORK_REMOTE`) are correctly set to avoid overwriting unintended branches. Use `git remote -v` to verify your remotes before proceeding.

  • File: docs/guides/README.md

    • Issue: The link descriptions in the "Available Guides" section could be more concise and consistent in tone.
    • Why it's an issue: Long descriptions reduce readability and detract from the streamlined format of the README.
    • Suggested Solution: Simplify the link descriptions for brevity. Example: 
      - [CI](./CI.md) - Guide to modifying and testing pipelines in the CI system.
- [Docker Build](./docker-build.md) - Instructions for building Docker images from source.
- [Cherry-Pick Pull Request](./cherry-pick-pull-request.md) - Steps for backporting changes to release branches.
- [FAQ](./FAQ.md) - Common troubleshooting tips for CI/CD workflows.

Best Practices

  • File: docs/guides/CI.md

    • Issue: The workflow diagram uses a mermaid syntax, but there is no guidance on how to render it when viewing the document locally.
    • Why it's an issue: Developers unfamiliar with mermaid diagrams may struggle to interpret or render the diagram.
    • Suggested Solution: Add a note in the "Workflow Diagram" section suggesting tools or plugins to render mermaid syntax. 
      **Note**: To view the workflow diagram, use a Markdown viewer that supports `mermaid` syntax, such as VS Code with the `Markdown Preview Mermaid Support` extension or GitHub's native rendering.

  • File: docs/guides/cherry-pick-pull-request.md

    • Issue: The "Handling Conflicts" section lacks examples of typical conflict scenarios and their resolutions.
    • Why it's an issue: While the general process is documented, practical examples would help developers unfamiliar with conflict resolution.
    • Suggested Solution: Add a short example of a conflict resolution process, highlighting common merge conflict markers (<<<<, ====, >>>>). 
      **Example Conflict Resolution**:
```diff
<<<<<<< HEAD
Original code in the target branch
=======
Code from the cherry-picked commit
>>>>>>> commit-hash
      Resolve by manually editing the file to incorporate the desired changes, then git add <resolved-files> and continue the cherry-pick.

  • File: docs/guides/cherry-pick-pull-request.md

    • Issue: The "Manual Cherry-Picking" section does not mention testing the cherry-picked changes.
    • Why it's an issue: Developers may forget to validate the cherry-pick functionality, leading to potential issues in production.
    • Suggested Solution: Add a step for testing the cherry-picked changes before pushing them. 
      3. Test the cherry-picked changes:
   ```bash
   # Example: Run unit tests to validate functionality
   make test

Testing Coverage

  • Missing: There is no mention of automated tests or validation for the cherry-picking script (cherry_pick_pull.sh).
  • Why it's an issue: Documentation assumes the script works as intended but does not encourage verifying it through tests.
  • Suggested Solution: Add a note recommending users run a dry run (DRY_RUN=1) before using the script for production tasks. 
    **Recommendation**: Before using the cherry-pick script in production, test its behavior with `DRY_RUN=1` to ensure it performs as expected.

Naming Conventions

  • File: docs/guides/cherry-pick-pull-request.md
    • Issue: The script name cherry_pick_pull.sh is inconsistent with typical naming conventions for automation scripts (e.g., using dashes instead of underscores).
    • Why it's an issue: Consistent naming improves readability and predictability.
    • Suggested Solution: Rename the script to cherry-pick-pull.sh for consistency.

Documentation Needs

  • Missing: Important commands/tools (e.g., gh auth login) are used without explicit cross-references to their documentation.
  • Why it's an issue: Developers unfamiliar with these tools may need additional guidance.
  • Suggested Solution: Embed inline links to relevant documentation for each tool or command used. Example: 
    - [GitHub CLI Authentication](https://cli.github.com/manual/gh_auth_login)

@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary

This PR introduces a new guide on cherry-picking pull requests to another branch, along with updates to the documentation index in README.md. The approach involves detailed documentation, including prerequisites, usage of a helper script, step-by-step instructions, troubleshooting, and best practices. The overall quality is good, but there are some areas where clarity and consistency can be improved to enhance the usability of the guide.

Critical Issues

No critical issues detected.

Code Improvements

1. Incomplete Description of Helper Script Behavior

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: 16-20
  • Issue: The helper script's behavior for edge cases (e.g., failed cherry-pick due to conflicts) is not fully detailed. While the general conflict resolution process is mentioned later, it would be helpful to note explicitly in the script description that manual intervention may be required.
  • Suggestion: Update the description to note that conflicts during cherry-picking may require manual resolution and the script will prompt the user in such cases.

2. Missing Example for Multiple Environment Variable Usage

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: 46-56
  • Issue: While individual environment variables (DRY_RUN, UPSTREAM_REMOTE, etc.) are explained, there is no example showing combined usage, which may be common during complex operations.
  • Suggestion: Add an example showcasing multiple environment variables used together: 
    GITHUB_USER=myusername DRY_RUN=1 REGENERATE_DOCS=1 ci-repo-cloned-path/scripts/ops/cherry_pick_pull.sh upstream/release-8.5 12345

3. Redundant Manual Cherry-Picking Section

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: 92-129
  • Issue: The manual cherry-picking section largely duplicates information already provided in the helper script steps. This redundancy may confuse users about which method to prefer.
  • Suggestion: Consolidate the manual cherry-picking section into a brief fallback note under "Troubleshooting" or provide a clear comparison of when to use the script versus manual cherry-picking.

Best Practices

1. Inconsistent Terminology

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: Throughout
  • Issue: Terms like "helper script" and "cherry-pick script" are used interchangeably, which might confuse readers.
  • Suggestion: Use consistent terminology, such as "helper script," throughout the guide.

2. Missing Hyperlink to Helper Script

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: 14
  • Issue: The path to the helper script (scripts/ops/cherry_pick_pull.sh) is mentioned but not hyperlinked for quick navigation.
  • Suggestion: Add a hyperlink to the script file if docume 8000 ntation is hosted online: 
    [`scripts/ops/cherry_pick_pull.sh`](https://github.com/<repo-path>/scripts/ops/cherry_pick_pull.sh)

3. Testing Recommendations

  • File: docs/guides/cherry-pick-pull-request.md
  • Lines: 121-123
  • Issue: The guide does not explicitly state how to test cherry-picked changes locally before creating a PR, which is a critical step.
  • Suggestion: Add a note under "Best Practices" recommending local testing: 
    Test the cherry-picked branch locally using the appropriate test suite or CI pipelines to ensure no regressions.

4. Improving README Cross-References

  • File: docs/guides/README.md
  • Lines: 9-12
  • Issue: The link to the "Cherry-Pick Pull Request" guide does not specify its relevance or audience.
  • Suggestion: Add a brief explanation in the link description: 
    - [Cherry-Pick Pull Request](./cherry-pick-pull-request.md) - Guide for developers and release managers to backport changes across branches using automated and manual methods.

Testing Coverage

  • No testing-related changes are included in this PR. Ensure that the helper script referenced in the guide is thoroughly tested for edge cases, such as merge conflicts or authentication failures, and that its behavior aligns with the documentation.

Documentation Needs

  • Consider adding a "Quick Reference" section to cherry-pick-pull-request.md summarizing key commands and options for advanced users.

wuhuizuo and others added 2 commits July 4, 2025 15:18
@wuhuizuo @gemini-code-assist
Update docs/guides/cherry-pick-pull-request.md
ce04fdc 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@wuhuizuo @gemini-code-assist
Update docs/guides/cherry-pick-pull-request.md
9681954 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary

This PR adds comprehensive documentation to the CI repository, including guides for PingCAP's CI system, cherry-picking pull requests, and organizing the docs/guides section. The approach emphasizes clarity through step-by-step instructions, diagrams, and best practices. The documentation structure is well-organized, but there are a few areas for improvement in terms of consistency and depth of content.

Critical Issues

None detected.

Code Improvements

  1. Inconsistent Variable Descriptions in Cherry-Pick Script Guide

    • File: docs/guides/cherry-pick-pull-request.md

    • Lines: 38-47

    • Issue: Environment variables like DRY_RUN and REGENERATE_DOCS are mentioned, but their purpose and usage are not entirely clear. For example, what does "regenerate documentation" involve, and how does it relate to cherry-picking?

    • Recommendation: Add more detailed descriptions for each environment variable, including examples if possible.

      - `REGENERATE_DOCS`: Automatically updates any documentation files affected by the cherry-pick. Use this if your changes involve files like `README.md` or other documentation.

  2. Missing Context for Helper Script Location

    • File: docs/guides/cherry-pick-pull-request.md

    • Lines: 15

    • Issue: The guide references the helper script's location (scripts/ops/cherry_pick_pull.sh) without explaining how contributors can locate it or whether it's included in the repository by default.

    • Recommendation: Add a note specifying where contributors can find the script (e.g., is it part of the cloned repository, or does it need to be downloaded separately?).

      Note: The `cherry_pick_pull.sh` script is located in the `scripts/ops` directory of the cloned repository. Ensure you have cloned the repository before proceeding.

Best Practices

  1. Testing Gaps

    • Files: docs/guides/CI.md, docs/guides/cherry-pick-pull-request.md

    • Lines: Multiple

    • Issue: While the guides describe workflows extensively, there is limited emphasis on testing best practices, such as verifying cherry-picked changes with unit tests or integration tests.

    • Recommendation: Add sections to each guide about testing, including commands or tools contributors can use to ensure their changes are functional.

      ## Testing Cherry-Picked Changes
Before creating a PR, test the cherry-picked changes locally using the repository's testing suite:
- Run `make test` to execute unit tests
- Run `make integration-test` for integration tests

  2. Unclear Assumptions in CI Workflow Guide

    • File: docs/guides/CI.md

    • Lines: 3-64

    • Issue: The guide assumes contributors are familiar with the CI system's directory structure (e.g., what /jobs, /pipelines, and /prow-jobs contain). New contributors may struggle to understand these terms without prior knowledge.

    • Recommendation: Add brief explanations or links to documentation that describe the directory structure and its purpose.

      ## Directory Structure Overview
- `/jobs`: Contains Jenkins job definitions, which define how CI jobs are executed.
- `/pipelines`: Contains implementation scripts for CI pipelines.
- `/prow-jobs`: Contains configuration files for Prow, an external CI tool.

  3. Missing Internal Links

    • File: docs/guides/README.md

    • Lines: 1-42

    • Issue: The README references other guides but doesn't provide internal links for quick navigation (e.g., FAQ, Docker Build).

    • Recommendation: Add internal links using relative paths.

      - [FAQ](./FAQ.md)

  4. Inconsistent Naming Conventions

    • File: docs/guides/README.md

    • Lines: 1-42

    • Issue: The guide titles in the README use inconsistent formatting (e.g., some titles are capitalized fully while others are sentence case).

    • Recommendation: Standardize guide titles to use sentence case for consistency.

      - [CI](./CI.md): Comprehensive guide to PingCAP's CI system
- [Docker build](./docker-build.md): Instructions for building Docker images

Suggested Next Steps

  1. Address the inconsistencies in variable descriptions and script references.
  2. Expand testing recommendations in guides to ensure contributors validate their changes effectively.
  3. Add introductory sections for CI directory structures to improve accessibility for new contributors.
  4. Standardize formatting and link usage across documentation files.

@wuhuizuo @gemini-code-assist
Update docs/guides/cherry-pick-pull-request.md
d703eae 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary

This pull request introduces well-documented guides for CI processes and cherry-picking pull requests, alongside reorganizing the documentation structure. The approach emphasizes clarity through step-by-step instructions, workflow diagrams, and practical examples. While the content is comprehensive and helpful, some areas could benefit from improved precision, additional context, and minor structural adjustments.

Critical Issues

No critical issues identified.

Code Improvements

  1. Missing Script Location in Cherry-Pick Guide

    • File: docs/guides/cherry-pick-pull-request.md
    • Line: 13
    • Issue: The cherry_pick_pull.sh script location is referred to but not explicitly provided. Users unfamiliar with the repository structure may struggle to locate it.
    • Suggestion: Provide a direct relative path from the repository root or clarify its exact location. Update the sentence: 
      The repository includes a helper script [`scripts/ops/cherry_pick_pull.sh`](../../scripts/ops/cherry_pick_pull.sh) located at `scripts/ops/cherry_pick_pull.sh` in the repository root.

  2. Ambiguity in Workflow Diagram

    • File: docs/guides/CI.md
    • Lines: 10-13
    • Issue: The mermaid diagram labels could be more descriptive, particularly for Seed job deploys to staging and Test in staging environment. Readers unfamiliar with CI terms might find this unclear.
    • Suggestion: Add annotations or footnotes explaining these terms in the guide text. For example: 
      - **Seed job**: A Jenkins job that deploys configurations to the staging environment automatically.  
- **Test in staging environment**: Running jobs manually in the staging Jenkins instance for validation.

  3. Testing Details Missing in Cherry-Picking Guide

    • File: docs/guides/cherry-pick-pull-request.md
    • Lines: 116-118
    • Issue: While the guide recommends testing cherry-picked changes, it lacks specifics on how to test (e.g., running CI jobs or functional tests).
    • Suggestion: Add a section detailing testing methodology, such as: 
      ### Testing Cherry-Picked Changes  
After completing the cherry-pick, validate the changes by running CI jobs in the staging environment or executing relevant tests locally. Ensure all impacted functionality works as expected.

Best Practices

  1. Cross-Linking Documentation

    • File: docs/guides/README.md
    • Lines: 5-11
    • Issue: The "Available Guides" section could benefit from more cross-links between related topics to improve navigation. For example, linking the FAQ guide under "CI/CD" for troubleshooting pipeline issues.
    • Suggestion: Add a cross-link in the README: 
      - [FAQ](./FAQ.md) - Frequently Asked Questions about CI/CD infrastructure, including pipeline troubleshooting (recommended for CI guide readers).

  2. Environment Variable Clarifications

    • File: docs/guides/cherry-pick-pull-request.md
    • Lines: 49-59
    • Issue: The environment variables (DRY_RUN, REGENERATE_DOCS, etc.) lack explicit examples or use cases, which might confuse new contributors.
    • Suggestion: Provide an example for each variable, e.g.: 
      DRY_RUN=1 ci-repo-cloned-path/scripts/ops/cherry_pick_pull.sh upstream/release-8.5 12345
# Simulates the cherry-pick without pushing changes or creating a PR.

  3. Guide Format Consistency

    • File: docs/guides/README.md
    • Lines: 33-38
    • Issue: The "Guide Format Recommendations" section outlines a structure but doesn't enforce its application across existing guides.
    • Suggestion: Revise existing guides to match the format (e.g., Prerequisites, Step-by-Step Instructions, etc.), ensuring uniformity.

Additional Notes

The guides are thorough and actionable, and the inclusion of troubleshooting and best practices is commendable. Addressing the above issues will further enhance user experience and reduce ambiguity for contributors unfamiliar with CI processes or Git operations.

@ti-chi-bot ti-chi-bot
Copy link
ti-chi-bot bot commented Jul 4, 2025

I have already done a preliminary review for you, and I hope to help you do a better job.

Summary

This pull request adds structured documentation to the CI repository, including a guide for cherry-picking pull requests, a comprehensive CI system guide, and updates to the README for improved organization. The approach involves creating detailed Markdown files with clear step-by-step instructions, diagrams, and examples. The documentation is well-organized and thorough, but there are minor areas for improvement in clarity, edge cases, and consistency.

Critical Issues

No critical issues were found in this pull request.

Code Improvements

  • File: docs/guides/cherry-pick-pull-request.md
    Issue: The helper script usage section lacks clarity on error handling during cherry-pick failures or script execution issues.
    Why: Users may encounter edge cases (e.g., network issues, authentication errors) that are not addressed in the current documentation.
    Suggestion: Add a subsection detailing possible error messages from the script and ways to troubleshoot them. For instance:

    ### Common Errors and Fixes
- **Error: Authentication failed**  
  Ensure you are authenticated with the GitHub CLI (`gh auth login`) and that your token has the correct permissions.
- **Error: Failed to apply patch**  
  Manually inspect the patch file and resolve conflicts using `git am --abort` and retry the cherry-pick manually.

  • File: docs/guides/CI.md
    Issue: The guide does not address rollback procedures for failed production deployments.
    Why: CI workflows often require rollback mechanisms to handle unexpected issues in production. The documentation is incomplete without this.
    Suggestion: Add a subsection about rolling back changes, e.g.:

    ## Rolling Back Changes
If a production deployment introduces issues:
1. Revert the changes in the staging directory.
2. Test the rollback in the staging environment.
3. Create a PR to move the reverted code to production.

Best Practices

  • File: docs/guides/cherry-pick-pull-request.md
    Issue: Missing inline examples for resolving merge conflicts during manual cherry-picking.
    Why: While general instructions are provided, inline examples can make the process clearer.
    Suggestion: Add a practical example of resolving a sample conflict:

    ### Example: Resolving a Conflict
Suppose the conflict occurs in `main.py`:
```diff
<<<<<<< HEAD
old code line
=======
new code line
>>>>>>> commit
90B9
-hash

    Resolve by choosing the correct line:

    new code line

    Then:

    git add main.py
git cherry-pick --continue

  • File: docs/guides/README.md
    Issue: Guide descriptions in the README are inconsistent in length and detail.
    Why: Uniform descriptions improve readability and make it easier for contributors to navigate the documentation.
    Suggestion: Standardize descriptions to a brief format, e.g.:

    - [CI](./CI.md): Guide on modifying, testing, and deploying pipelines using PingCAP's CI system.
- [Cherry-Pick Pull Request](./cherry-pick-pull-request.md): Instructions for cherry-picking pull requests to other branches, including conflict resolution.

Testing Coverage Gaps

  • File: docs/guides/cherry-pick-pull-request.md
    Issue: The guide does not mention validating cherry-picked changes.
    Why: It's critical to ensure that cherry-picked changes function correctly in the target branch before merging.
    Suggestion: Add a note about testing: 
    ## Testing Cherry-Picked Changes
After completing the cherry-pick, test the changes locally:
- Run all relevant unit and integration tests.
- Verify that the cherry-picked features or fixes work as expected in the target branch.

Style Guideline Deviations

  • File: docs/guides/CI.md
    Issue: Inconsistent capitalization in section headers (e.g., "Workflow Diagram" vs. "Step-by-Step Guide").
    Why: Consistent capitalization improves the visual structure of the document.
    Suggestion: Use sentence case for all headers: 
    ### Workflow diagram
### Step-by-step guide

The documentation is overall high quality, but addressing these improvements will enhance clarity, usability, and completeness.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments

Assignees
No one assigned
Labels
size/XL
Projects
EE - CI/CD system
Status: No status
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
1 participant
@wuhuizuo
0