docs: update readme (#5544)

* docs: update readme * docs: update readme en-US * docs: add CONTRIBUTING.md * chore: add a readme image and demo * fix: ci * chore: fix ci
antvis · Mar 15, 2024 · 5dcbb5e · 5dcbb5e
1 parent 810f982
commit 5dcbb5e
Show file tree

Hide file tree

Showing 7 changed files with 557 additions and 270 deletions.
diff --git a/CONTRIBUTING.en-US.md b/CONTRIBUTING.en-US.md
@@ -0,0 +1,64 @@
+# Contribution Guide
+
+## Introduction
+
+First of all, thank you for considering contributing to G6! It's people like you that make the open-source community such a fantastic place to learn, inspire, and create. This document provides guidelines for contributing to G6. Please respect these guidelines to help maintain a collaborative and inclusive environment.
+
+## Ways to Contribute
+
+There are many ways you can contribute to G6:
+
+- **Reporting bugs**: If you find a bug, please check the issue tracker to see if it has already been reported. If not, open a new issue. Be sure to include a clear title, a detailed description, and as much relevant information as possible.
+- **Suggesting enhancements**: New ideas are always welcome. Open an issue to suggest improvements or new features.
+- **Writing documentation**: Good documentation is as important as the code itself. If you enjoy writing and are looking to help out, consider improving the docs.
+- **Submitting pull requests**: Pull requests are essential for us to keep moving forward. Whether it's fixing a bug, implementing a feature, or improving documentation, every contribution is valuable.
+
+## Getting Started
+
+Before starting to contribute, make sure to:
+
+1. Fork the repository and create your branch from `v5s`.
+2. If you're adding code, add tests that cover the new functionality/bug fix.
+3. Ensure the test suite passes locally.
+4. If you've changed APIs, update the documentation.
+5. Make sure your code lints.
+6. Write a clear log message for your commits. One-line messages are fine for small changes, but bigger changes should include more detail.
+
+## Pull Request Process
+
+1. Make sure your code adheres to the project's coding conventions (indentation, accurate comments, etc.) and that all of your commits are signed.
+2. Update the README.md with any changes that are crucial to the project.
+3. Increase the version numbers in any examples files and the README.md to the new version that this Pull Request would represent.
+4. You may merge the Pull Request in once you have the sign-off of two other developers, or if you do not have permission to do that, you may request the second reviewer to merge it for you.
+
+## How to run the Project
+
+- Install dependence:
+
+```bash
+$ pnpm install
+```
+
+- Debugger with live demo:
+
+```bash
+$ cd packasges/g6
+
+$ npm run dev
+```
+
+- Run test cases:
+
+```bash
+$ cd packasges/g6
+
+$ npm run test
+```
+
+- Preview locale website:
+
+```bash
+$ cd packasges/site
+
+$ npm run dev
+```
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,64 @@
+# 贡献指南
+
+## 引言
+
+首先，感谢您考虑为 G6 做出贡献！正是像您这样的人才让开源社区成为一个学习、启发和创造的绝佳场所。本文档提供了对 G6 做出贡献的指导原则。请遵守这些指南，以帮助维护一个协作和包容的环境。
+
+## 贡献方式
+
+您可以通过多种方式为 G6 做出贡献：
+
+- **报告错误**：如果您发现一个错误，请检查问题跟踪器，看看它是否已经被报告过。如果没有，请开设一个新的问题。确保包含一个清晰的标题、详细的描述以及尽可能多的相关信息。
+- **建议增强功能**：新想法总是受欢迎的。开设一个问题以建议改进或新增功能。
+- **编写文档**：良好的文档和代码本身一样重要。如果您喜欢写作并希望帮忙，请考虑改善文档。
+- **提交拉取请求（Pull Requests）**：拉取请求对我们保持持续进步至关重要。无论您是在修复一个错误、实现一个功能还是改进文档，每一份贡献都是宝贵的。
+
+## 开始之前
+
+在开始贡献之前，请确保：
+
+1. Fork 仓库并从 `v5` 分支创建您自己的分支。
+2. 如果您添加代码，请添加覆盖新功能/错误修复的测试。
+3. 确保本地测试套件通过。
+4. 如果您更改了 API，请更新文档。
+5. 确保您的代码遵循规范。
+6. 为您的提交写一个清晰的日志消息。对于小的更改，一行消息就足够了，但更大的更改应包括更多的细节。
+
+## 拉取请求流程
+
+1. 确保您的代码符合项目的编码规范（缩进、准确的注释等），并且您的所有提交都已签名。
+2. 如果有对项目至关重要的更改，请更新 README.md。
+3. 将任何示例文件和 README.md 中的版本号增加到这个拉取请求所代表的新版本。
+4. 一旦您得到两个其他开发者的签署，您可以合并拉取请求，如果您没有权限这样做，您可以请求第二个审阅者为您合并。
+
+## 启动项目
+
+- 安装依赖：
+
+```bash
+$ pnpm install
+```
+
+- 调试 DEMO
+
+```bash
+$ cd packasges/g6
+
+$ npm run dev
+```
+
+- 运行单元测试
+
+```bash
+$ cd packasges/g6
+
+$ npm run test
+```
+
+- 启动本地官网
+
+```bash
+$ cd packasges/site
+
+$ npm run dev
+```
diff --git a/README.en-US.md b/README.en-US.md
@@ -1,193 +1,127 @@
-# G6: A Graph Visualization Framework in TypeScript
 
-> The 5.0 beta version is currently undergoing rapid iteration, with the stable release expected on June 6, 2024. There may be changes to the API during this period, so please exercise caution when using it in stable online product.
+<img src="https://gw.alipayobjects.com/zos/antfincdn/R8sN%24GNdh6/language.svg" width="18"> English | [简体中文](./README.md)
+
+<h1 align="center">
+<b>G6: A Graph Visualization Framework in TypeScript</b>
+</h1>
+
+> The G6 5.0 beta version has been released. There are still many details and experience issues, and we welcome you to try it out and provide feedback. Use it with caution in production environments for now. The official version will be released with 6.6!
 
 ![](https://user-images.githubusercontent.com/6113694/45008751-ea465300-b036-11e8-8e2a-166cbb338ce2.png)
 
-[![npm Version](https://img.shields.io/npm/v/@antv/g6.svg)](https://www.npmjs.com/package/@antv/g6)
-![typescript](https://img.shields.io/badge/language-typescript-red.svg)
+[![npm Version](https://img.shields.io/npm/v/@antv/g6.svg@beta)](https://www.npmjs.com/package/@antv/g6)
 [![Build Status](https://github.com/antvis/g6/workflows/build/badge.svg?branch=v5)](https://github.com/antvis/g6/actions)
 [![Coverage Status](https://coveralls.io/repos/github/antvis/G6/badge.svg)](https://coveralls.io/github/antvis/G6)
 [![npm Download](https://img.shields.io/npm/dm/@antv/g6.svg)](https://www.npmjs.com/package/@antv/g6)
+![typescript](https://img.shields.io/badge/language-typescript-blue.svg)
 [![npm License](https://img.shields.io/npm/l/@antv/g6.svg)](https://www.npmjs.com/package/@antv/g6)
-[![Percentage of issues still open](http://isitmaintained.com/badge/open/antvis/g6.svg)](http://isitmaintained.com/project/antvis/g6)
 
-[中文 README](README.md)
+<p align="center">
+ <a href="https://g6-next.antv.antgroup.com/">Introduction</a> •
+ <a href="https://g6-next.antv.antgroup.com/examples">Examples</a> •
+ <a href="https://g6-next.antv.antgroup.com/">Tutorial</a> •
+ <a href="https://g6-next.antv.antgroup.com/">API</a>
+</p>
 
-## What is G6
+[G6](https://github.com/antvis/g6) is a graph visualization engine. It provides basic capabilities for graph visualization and analysis such as drawing, layout, analysis, interaction, animation, themes, and plugins. With G6, users can quickly build their own graph visualization and analysis applications, making relational data simple, transparent, and meaningful.
 
-[G6](https://github.com/antvis/g6) is a graph visualization engine, which provides a set of basic mechanisms, including rendering, layout, analysis, interaction, animation, and other auxiliary tools. G6 aims to simplify the relationships, and help people to obtain the insight of relational data.
+<img src='https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*_PJ5SZELwq0AAAAAAAAAAAAADmJ7AQ/original' width=550 alt='' />
 
 <img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*zTjwQaXokeQAAAAAAAAAAABkARQnAQ' width=550 alt='' />
 
-Developers are able to build graph visualization **analysis** applications or graph visualization **modeling** applications easily.
-
 <img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*zau8QJcVpDQAAAAAAAAAAABkARQnAQ' height=200 alt='' /><img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*RIlETY_S6IoAAAAAAAAAAABkARQnAQ' height=200 alt='' />
 
-<img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*cDzXR4jIWr8AAAAAAAAAAABkARQnAQ' height=150 alt='' /><img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*DifbSahOblAAAAAAAAAAAABkARQnAQ' height=150 alt='' /><img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*HTasSJGC4koAAAAAAAAAAABkARQnAQ' height=150 alt='' />
-
-> Powerful Animation and Interactions
-
-<img src="https://user-images.githubusercontent.com/6113694/44995293-02858600-afd5-11e8-840c-349e4730d63d.gif" height=150 alt='' /><img src="https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*I9OdTbXJIi0AAAAAAAAAAABkARQnAQ" height=150 alt='' /><img src="https://user-images.githubusercontent.com/6113694/44995332-2ba61680-afd5-11e8-8cab-db0e9d08ceb7.gif" height=150 alt='' />
-
-<img src="https://gw.alipayobjects.com/zos/rmsportal/HQxYguinFOMIXrGQOABY.gif" height=150 alt='' /><img src="https://gw.alipayobjects.com/zos/rmsportal/nAugyFgrbrUWPmDIDiQm.gif" height=150 alt='' /><img src="https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*xoufSYcjK2AAAAAAAAAAAABkARQnAQ" height=150 alt='' />
-
-> Powerful Layouts
-
-## Features (5.0 Alpha)
-
-- Extensionable: All the modules (seven types) are integrated as plugins;
-- Style and animation standards, supports level of details (see the graph below);
-- Beautiful Built-in Theme and cound be customized (see the graph below);
-- Layouts with Great Performance: More than 10 layout algorithms, supports GPU and Rust parallel computing, and custom layouts;
-- Steerable Interactions: More than 10 basic interaction behaviors ;
-- Friendly User Experience: Complete documents for different levels of user requirements. TypeScript supported.
-- Multiple renderers: Canvas, SVG, WebGL;
-- 3D Graph:
-
-The gif is not fully loaded, [Click Here to See the Original Image](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*qPrmQrdV77gAAAAAAAAAAAAADmJ7AQ/original)
-
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*IUOnSbLisyoAAAAAAAAAAAAADmJ7AQ/original" width=600 height=334 alt='' />
-
-> 3D Graph
-
-The gif is not fully loaded, [Click Here to See the Original Image](https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*1BFvQ4r3P7UAAAAAAAAAAAAADmJ7AQ/original)
+<img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*cDzXR4jIWr8AAAAAAAAAAABkARQnAQ' height=150 alt='' /><img src='https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*HTasSJGC4koAAAAAAAAAAABkARQnAQ' height=150 alt='' />
 
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*tPPGSokdSYsAAAAAAAAAAAAADmJ7AQ/original" width=600 height=367 alt='' />
+<img src="https://user-images.githubusercontent.com/6113694/44995293-02858600-afd5-11e8-840c-349e4730d63d.gif" height=150 alt='' /><img src="https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*I9OdTbXJIi0AAAAAAAAAAABkARQnAQ" height=150 alt='' /><img src="https://gw.alipayobjects.com/mdn/rms_f8c6a0/afts/img/A*xoufSYcjK2AAAAAAAAAAAABkARQnAQ" height=150 alt='' />
 
-> Animations and Level of Details
 
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*QjJoSbD7GTwAAAAAAAAAAAAADmJ7AQ/original" width=800 height=226 alt='' />
+## ✨ Features
 
-> Built-in Themes and Custom Themes
+G6, as a professional graph visualization engine, boasts the following features:
 
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*x7NTT5_baKYAAAAAAAAAAAAADmJ7AQ/original" width=400 height=218 alt='' />
+- **Rich Elements**: It comes with a variety of built-in node, edge, and Combo UI elements with extensive style configurations, supports data callbacks, and has a flexible mechanism for extending custom elements.
+- **Controllable Interactions**: It includes more than 10 built-in interaction behaviors and offers a rich array of events, facilitating the expansion of custom interactive behaviors.
+- **High-Performance Layout**: The engine features more than 10 common graph layouts, some of which leverage GPU and Rust parallel computing for enhanced performance, and it supports custom layout development.
+- **Convenient Plugins**: Optimized built-in plugin functionality and performance, with flexible extensibility, making it easier to implement customized business capabilities.
+- **Multiple Theme and Palettes**: Provides two sets of built-in themes, light and dark, that integrate over 20 popular community color palettes based on the AntV new color scheme.
+- **Multi-Environment Rendering**: Harnessing the power of [G](https://github.com/antvis/g), it supports rendering in Canvas, SVG, and WebGL, as well as server-side rendering with Node.js; it also offers plugin packages that provide powerful 3D rendering and spatial interactions based on WebGL.
+- **React Ecosystem**: By utilizing the React front-end ecosystem, it supports React nodes, significantly enriching the presentational styles of G6 nodes.
 
-> Seven Types of Plugins
 
-- (TODO: migrate from v4) Abundant Built-in Items: Nodes and edges with free configurations;
-- (TODO: migrate from v4) Convenient Components: Outstanding ability and performance;
+## 🔨 Getting Started
 
-G6 concentrates on the principle of 'good by default'. In addition, the custom mechanism of the item, interaction behavior, and layout satisfies the customazation requirements.
-
-> Abundant Built-in Items
-
-## Installation (5.0 Alpha)
+G6 is usually installed via a package manager such as npm or Yarn.
 
 ```bash
-$ npm install @antv/g6@5.0.0-beta.28
+$ npm install @antv/g6@next
 ```
 
-## Usage (5.0 Alpha)
-
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*M-MTRaLiZN0AAAAAAAAAAAAADmJ7AQ/original" width=437 height=148 alt='' />
-
-The configuration specification of the graph can be refered to: https://github.com/antvis/G6/blob/v5/packages/g6/src/types/spec.ts
-
-Graph API: https://github.com/antvis/G6/blob/2b44df189dd2e851447ba5a09541c372b49cd658/packages/g6/src/types/graph.ts#L23
+```bash
+$ yarn add @antv/g6@next
+```
 
-A simple graph demo:
+The `Graph` object then can be imported from G6.
 
-<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*M-MTRaLiZN0AAAAAAAAAAAAADmJ7AQ/original" width=437 height=138 alt='' />
+```html
+<div id="container"></div>
+```
 
-[![Edit compassionate-lalande-5lxm7](https://codesandbox.io/static/img/play-codesandbox.svg)](https://codesandbox.io/embed/musing-matan-q255po?fontsize=14&hidenavigation=1&theme=dark)
 
-```js
-import { Graph } from "@antv/g6";
+```ts
+import { Graph } from '@antv/g6';
 
+// Get the Data.
 const data = {
- nodes: [
- {
- id: "node1",
- label: "Node 1",
- data: {
- x: 150,
- y: 150,
- },
- },
- {
- id: "node2",
- label: "Node 2",
- data: {
- x: 400,
- y: 150,
- },
- },
- ],
- edges: [
- {
- id: "edge1",
- label: "Edge 1",
- source: "node1",
- target: "node2",
- data: {},
- },
- ],
+ nodes: [/* your nodes data */],
+ edges: [/* your edges data */],
 };
 
+// Create the Graph instance.
 const graph = new Graph({
- container: "container",
- width: 500,
- height: 500,
+ container: 'container',
+ autoFit: 'view',
  data,
- node: (innerModel) => ({
- ...innerModel,
- type: "circle",
- data: {
- ...innerModel.data,
- labelShape: {
- text: innerModel.label,
- },
- labelBackgroundShape: {},
- iconShape: {
- img: "https://gw.alipayobjects.com/zos/basement_prod/012bcf4f-423b-4922-8c24-32a89f8c41ce.svg",
- },
- },
- }),
- edge: (innerModel) => ({
- ...innerModel,
- type: "line",
- data: {
- labelShape: {
- text: innerModel.label,
- },
- labelBackgroundShape: {},
- },
- }),
+ node: {
+ palette: {
+ type: 'group',
+ field: 'cluster',
+ }
+ },
+ layout: {
+ type: 'force',
+ },
+ behaviors: ['drag-canvas', 'drag-node'],
 });
-```
 
-## Development (5.0 Alpha)
+// Render the Graph.
+graph.render();
+```
 
-```bash
-# install dependencies by pnpm in the root directory
-$ pnpm install
+All goes well, you can get the following lovely graph!
 
-# enter packages/g6
-$ cd ./packages/g6
+<img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*ue4iTYurc6sAAAAAAAAAAAAADmJ7AQ/fmt.webp" height="300" />
 
-# build g6
-$ npm run build
 
-# start the integration demos
-$ npm run dev
+## 🌍 Ecosystem
 
-# run test case
-$ npm run test
+- **Ant Design Charts**: A React chart library based on G2, G6, X6, L7.
+- **Graphin**: A simple React wrapper based on G6, as well as an SDK for developing graph visualization applications.
 
-# run test case in watch mode
-npm test -- --watch ./tests/unit/node-spec
-DEBUG_MODE=1 npm test -- --watch ./tests/unit/node-spec
-```
+For more ecosystem open-source projects, contributions are welcome. Please feel free to submit a PR for inclusion.
 
-## Documents (5.0 Alpha)
 
-The documents will be ready after the 5.0 version being stable.
+## 📮 Contributing
 
-## How to Contribute
+- **Issue Reporting**: If you encounter any issues with G6 during use, please feel free to submit an issue, along with the minimal sample code that can reproduce the problem.
+- **Contribution Guide**: Information on how to get involved in the development and contribution to G6.
+- **Ideas Discussion**: Discuss your ideas on GitHub Discussions or in the DingTalk group.
 
-Please let us know what you are you going to help. Do check out [issues](https://github.com/antvis/g6/issues) for bug reports or suggestions first.
+<div align="center">
+ <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*CQoGSoFBzaUAAAAAAAAAAAAADmJ7AQ/fmt.webp" height="256" />
+ <img src="https://mdn.alipayobjects.com/huamei_qa8qxu/afts/img/A*yXJGSY8RC68AAAAAAAAAAAAADmJ7AQ/fmt.webp" height="256" />
+</div>
 
-## License
+## 📄 License
 
-[MIT license](./LICENSE).
+[MIT](./LICENSE).