Release Notes

To deploy your preview documentation website, you can choose one of the following methods:

1. Deploy your website using a cloud service, such as Vercel, Cloudflare Pages, and Netlify:

   • Deploy your website using Vercel

   • Deploy your website using Cloudflare Pages

   • Deploy your website using Netlify

2. Deploy your website locally on your machine:

   • Deploy your website locally

Make sure that you have enabled GitHub Actions for your fork.

1. Create a pull request to one of the following repositories:

   • pingcap/docs

   • pingcap/docs-cn

   • pingcap/docs-tidb-operator

2. In your fork, create a new branch from the main branch following these naming conventions:

   Documentation	Branch naming convention
   TiDB (English)	preview/pingcap/docs/{PR_NUMBER}
   TiDB (Chinese)	preview/pingcap/docs-cn/{PR_NUMBER}
   TiDB Cloud	preview-cloud/pingcap/docs/{PR_NUMBER}
   TiDB Operator	preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}

3. The sync_pr.yml workflow is automatically triggered to update the content from the pull request.

1. Create a pull request to one of the following repositories:

   • pingcap/docs

   • pingcap/docs-cn

   • pingcap/docs-tidb-operator

2. In your fork, create a new branch from the main branch following these naming conventions:

   Documentation	Branch naming convention
   TiDB (English)	preview/pingcap/docs/{PR_NUMBER}
   TiDB (Chinese)	preview/pingcap/docs-cn/{PR_NUMBER}
   TiDB Cloud	preview-cloud/pingcap/docs/{PR_NUMBER}
   TiDB Operator	preview-operator/pingcap/docs-tidb-operator/{PR_NUMBER}
   git clone https://github.com/Oreoxmt/pingcap-docsite-preview.git cd pingcap-docsite-preview git checkout -b preview/pingcap/docs/{PR_NUMBER}

3. Execute the sync_pr.sh script to update the content from the pull request.
   

   ./sync_pr.sh

   This script automatically synchronizes document changes from the pull request and commits them to the current branch. To update the remote branch with these changes, be sure to push the commit.

To test a shell script, follow these steps:

1. Define the test configuration in test_config.toml. For example, to test the sync_scaffold.sh script, configure as follows:

   [sync_scaffold] diff_command = "diff -qrs data actual --exclude temp --exclude '*.log' --exclude sync_scaffold.sh" test_target = "sync_scaffold.sh" [[sync_scaffold.test_cases]] name = "Sync scaffold from a commit" args = "265874160aec258f9c725b0e940bc803ca558bda" directory = "test/sync_scaffold/"

2. Run the test using python3 test/test.py:

   $ python3 test/test.py Running Tests... 100%|█████████████████████████████████████████████████████████████████████████████| 1/1 [00:18<00:00, 18.78s/it] --------------------------------------------------Test Results-------------------------------------------------- ✅ Test Sync scaffold from a commit passed successfully Tests passed: 1 of 1 18.80s ----------------------------------------------------------------------------------------------------------------

• DocSitePreviewTest._setup_test_env(): clean up the test environment, copy the target script to the test environment, and ensure that the script can be executed.

• DocSitePreviewTest.execute(): execute the target script in the test environment and save the output in the test/.../actual directory.

• DocSitePreviewTest.verify(): compare the actual output (test/.../actual) with the expected output (test/.../data).

For more details, see this blog.

In the pingcap-docsite-preview context, scaffold refers to a specific set of elements synchronized from pingcap/docs-staging. These elements are crucial for the structure and navigation of the documentation website. It contains the following elements:

• Version selection: the docs.json file

• Table of contents: all TOC.md files in the markdown-pages directory

• Index pages: all _index.md files in the markdown-pages directory

• Homepage: all _docHome.md files in the markdown-pages directory

After executing the sync_scaffold.sh script, it updates the markdown-pages/ directory and the docs.json file.

This script modifies the repository as follows: