Creating a Branch

The default branch for VChart is the develop branch. Whether it's for feature development, bug fixes, or documentation writing, please create a new branch before merging it into the develop branch. Use the following code to create a branch:

// Create a documentation/demo branch
git checkout -b docs/add-funnel-demo

Finding or Creating an Issue

In principle, we require that each PR must have a corresponding issue. Before starting development, please ensure there is a corresponding issue, and that the issue is not already claimed.

Searching for Demo Issues

You can search for demo-related issues using the following method:

 label:demos

Some features may have the doc label associated with them. Check further if the issue is purely a demo task.

Creating a Demo Issue

Click "NEW ISSUE" to open the issue selection page and choose "Others."

Fill in the information related to the document issue you want to submit, and tag it with "demos."

Claiming an Issue

If you want to submit a demo or fix a demo bug, you can leave a message in the issue to claim it. The administrator will contact you, and after confirmation, assign the issue to you.

For example:

Creating or Modifying a Demo

The location of VChart documentation and demos within the project is as follows (examples):

Taking the example document of a basic area chart as an example (currently, a single example contains both Chinese and English versions, located under the paths zh & en respectively):

Example Markdown content is divided into several parts:

Metadata: Attribute definitions of the example content, including chart category, cover image, keywords, etc.
Title: The main content under the first-level title corresponds to the description information of the example.
Key Configuration: Explanation of the key configurations included in the example, which will be displayed in the "Key Configuration" section on the right side of the example page.
Code Demonstration: The specific code content executed in the example; currently only native JavaScript code is supported.

The field definitions of Markdown metadata are:

group: The classification information of the example, describing which chart category the current example belongs to.
title: The example title
keywords: Keywords of the example
order: The order criterion of the example within the same group
cover: The cover image of the example
tutorial: The tutorial link to jump to (the default example tutorial will jump to the tutorial corresponding to the example group)

Currently, chart examples in the group include multiple categories such as area chart, bar chart, combination, storytelling, etc., corresponding to all categories under the vchart example gallery. Refer to existing example documents for specific classification fields.

Finally, add the new demo path in docs/assets/examples/menu.json so that it can be previewed during rush docs and displayed on the official website.

Writing Demos with the Help of Doubao Marscode AI Programming Assistant

Marscode AI Programming Assistant

With the help of Doubao Marscode AI Programming Assistant, you can get comprehensive assistance throughout the document creation process.

If you haven't installed the Marscode AI Programming Assistant, please download it from this link: https://www.marscode.cn/home?utm_source=developer&utm_medium=oss&utm_campaign=visactor_a

During demo writing, using context instructions reasonably can improve content accuracy.

**⭐️ #Workspace**

Select global code in the Workspace as context; AI will automatically find related code Context according to user Query.

**⭐️ #Files**

Search and select files in the code repository as context

**⭐️ #Code**

Search and select functions or classes in the code repository as context

Below is an example of how to use the Marscode AI Programming Assistant for demo writing.

5.1 Providing a Document Framework

Here invoke #Workspace, then ask a question, select a document content of an example and hope it generates a new example document in the same manner.

We can continue to make adjustments on this basis.

5.2 Generating Descriptive Text

The description text for each demo can be initially generated using Marscode, and then proofread and adjusted. For example:

5.3 Generating Example Code

To better explain principles and usage, it is usually necessary to provide a runnable demo. The code generation capability of Marscode can be used to generate example code. However, the current code generation capabilities of various AIs cannot guarantee accuracy and require further verification.

5.4 Content Retrieval

Usually, in each Q&A, Marscode will provide reference documents, which can offer more contextual references for further analysis.

You can also perform file retrieval directly:

Submitting Code

After the document is completed, push the code to your remote branch, for example:

git commit -a -m "docs: add custom funnel demo and related docs"

The commit message for VisActor follows the Conventional Commits convention. For demo, use docs

<type>[optional scope]: <description>

Common type includes docs (documentation/log modifications), feat (new feature), fix (bug fix), refactor (code restructuring), etc., please choose based on the actual situation.

Please write the description in brief and precise English.

Before submitting a commit, we perform a commit lint check, which you can check in the check rules.

A common issue is that the remote upstream (@visactor/vchart) has new updates, which can lead to conflicts during the submission of a Pull Request. Thus, before submission, you can merge the commits from other developers remotely into your commit. Use the following code to switch to the develop branch: