diff --git a/docs/assets/guide/en/tutorial_docs/Contribution_Guide.md b/docs/assets/guide/en/tutorial_docs/Contribution_Guide.md new file mode 100644 index 0000000000..1c78d7b942 --- /dev/null +++ b/docs/assets/guide/en/tutorial_docs/Contribution_Guide.md @@ -0,0 +1,206 @@ +First of all, I would like to give you a thumbs up 👍🏻 for choosing to contribute to the open source community. Also, thank you very much for choosing to participate in the VisActor community and contribute to this open source project. + +## VChart Contribution Guide + +The VisActor team usually develops and maintains issues on GitHub. Please open the [GitHub website](https://github.com/), click the `Sign up `button in the upper right corner, register your own account, and take the first step in your open source journey. + +If you cannot open the Github site due to special circumstances, please inform us and proceed with project development through [Gitee](https://gitee.com/VisActor/VChart). + +In the [VChart repository](https://github.com/VisActor/VChart), we have a [guide ](https://github.com/VisActor/VChart/blob/develop/CONTRIBUTING.md)for all open source contributors on versioning, branching, and more. **Please take a few minutes to read about it** . + +## Your first PullRequest + +### Step 0: Install Git + +Git is a version control system used to track and manage code changes in software development projects. It helps developers record and manage the history of code, facilitating team collaboration, code version control, merging code, and other operations. With Git, you can track each version of each file and easily switch and compare between different versions. Git also provides branch management functionality, allowing for multiple parallel development tasks to be performed simultaneously. + +- Visit the official Git website: [https://git-scm.com](https://git-scm.com/) +- Download the latest version of the Git installer. +- Run the downloaded installation program and follow the prompts of the installation wizard to install. +- After the installation is complete, you can use the Command Line command `git version `to confirm the installation is successful. + +### Step 1: Fork the project + +- First, you need to fork this project, enter the [VChart project page](https://github.com/VisActor/VChart), and click the Fork button in the upper right corner + +![](/vchart/guide/contribution-guide/fork.PNG) + +- The project Your_Github_Username/vchart will appear in your GitHub account +- Use the following command on your local computer: Get a VChart folder + +``` +// ssh +git clone git@github.com:Your_Github_Username/VChart.git +// https +git clone https://github.com/Your_Github_Username/VChart.git +``` + +### Step 2: Get the project code + +- Go to the VChart folder and add the remote address of the VChart + +``` +git remote add upstream https://github.com/VisActor/VChart.git +``` + +- Get the latest source code of VChart + +``` +git pull upstream develop +``` + +### Step 3: Create a branch + +- Okay, now we can start contributing our code. The default branch of VChart is the develop branch. Whether it's feature development, bug fixing, or documentation writing, please create a new branch and merge it into the develop branch. Use the following code to create a branch: + +``` +// Create a feature development branch +git checkout -b feat/xxxx + +// Create a issue-fix development branch +git checkout -b fix/xxxx + +// Create documentation and demo branches +git checkout -b docs/add-funnel-demo +``` + +Suppose we create a document modification branch `docs/add-fund-demo` + +- Now we can change the code on the branch + +- Assuming we have added some code and submitted it to the codebase + +- Git commit -a -m "docs: add custom funnel demo and related docs". The commit information of VisActor follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)specification + + - `[optional scope]: ` + - The commonly used `types `include docs (document, log modification), feat (new feature), fix (problem repair), refactor (Code Refactoring), etc. Please choose according to the actual situation. + - Please write a brief and accurate description in English. + - Before submitting the commit, we will perform a commit lint check, you can check the [rules](https://github.com/VisActor/VChart/blob/98711490e90532d896dd9e44dd00a3af5b95f06d/common/autoinstallers/lint/commitlint.config.js) + +### Step 4: Merge and modify + +- A common issue is that remote upstream (@visactor/vchart) has new updates, which can cause conflicts when we submit Pull Requests. Therefore, we can merge the commits of other remote developers with ours before submitting. Use the following code to switch to the develop branch. + +``` +git checkout develop +``` + +- Use the following code to pull out the latest remote code: + +``` +git pull upstream develop +``` + +- Switch back to your own development branch. + +``` +git checkout docs/add-funnel-demo +``` + +- Merge the develop commit into your own branch. + +``` +git rebase develop +``` + +- Submit the updated code to your own branch. + +``` +git push upstream docs/add-funnel-demo +``` + +### Step 5: Submit Pull Request + +You can click the `Compare & Pull Request `button on your GitHub repository page. + +![](/vchart/guide/contribution-guide/create-PR.png) + +Or create via the `contribute `button: + +
+ +
+ +Fill in the submitted modification content according to the template. + +- Check what type of modification this is + +
+ +
+ +- Fill in the associated issue + +
+ +
+ +- If there are complex changes, please explain the background and solution + +
+ +
+ +After filling in the relevant information, click Create pull request to submit. + +## Getting Started with VChart Contribution + +" **Good first issue** " is a common hashtag in the open source community, and the purpose of this hashtag is to help new contributors find problems that are suitable for beginners. + +VChart beginner questions, you can view through the [issues list](https://github.com/VisActor/VChart/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22), currently includes two categories: + +- Demo case production +- Simple feature development + +If you currently **have time and willingness** to participate in community contributions, you can take a look at the **good first issue** in the issue and choose a claim that is interested and suitable for yourself. + +I believe you must be a colleague who has a beginning and an end. Therefore, when you understand and decide to claim an issue, please leave a message under the issue to inform everyone. + +### Demo Task Development Guide + +We have prepared some common cases in practical application scenarios and need to consider how to utilize the capabilities of VChart to achieve them. + +You can get started with using VChart through this type of task. VChart provides rich capabilities, and everyone may have different implementation ideas. **You can leave a message under the issue and discuss your own plan with everyone** . + +After completing the task, you can submit the self-made case to the official website demo for more people in need to learn and use. + +All demos are stored in the `docs/assets/examples `directory + +1. Please create a new `docs/*** `or `demo/*** `branch based on the develop branch for development +2. (If you have already installed, skip this step) Global installation [@microsoft/rush](https://rushjs.io/pages/intro/get_started/): `npm i --global @microsoft/rush` +3. Run `rush update` +4. Run `rush docs `to preview the current demo content locally +5. `Docs `directory + 1. `Docs/assets/examples/menu.json `Add your demo information to the directory file + 2. Complete the Chinese and English demo documents in the `zh `/ `en `directory respectively + 3. Add the demo preview image in the `docs/public/vchart/preview `directory and update the relative path in the demo document +6. Submit all code and create a Pull Request on Github, inviting others to review + +### Feature Task Development Guide + +We have prepared some simple and easy-to-use feature development tasks. If you have a certain foundation in JavaScript/TypeScript, you can claim these tasks. + +You can understand the VChart code architecture faster through requirement development. **You can leave a message under the issue and discuss your own plan with everyone** . + +1. Please create a new `feat/*** `branch based on the develop branch for development +2. (If you have already installed, skip this step) Global installation [@microsoft/rush](https://rushjs.io/pages/intro/get_started/): `npm i --global @microsoft/rush` +3. Run `rush update` +4. Run `rush start ` to start demo page: + 1. You can create a index.page page under `develop/packages/vchart/__tests__/runtime/browser `to import your own created development use cases +5. Confirm that all tests pass the `rush test` +6. After development is finished, run `rush change `command, write changelog and submit +7. Submit all code and create a Pull Request on Github, inviting others to review + +## Embrace the VisActor community + +In addition to contributing code to VisActor, we encourage you to participate in other things that make the community more prosperous, such as: + +1. Provide suggestions for project development, functional planning, etc +2. Create articles, videos, and hold lectures to promote VisActor. +3. Write promotion plan and execute it together with the team + +VisActor is also working hard to help colleagues who participate in community building grow together. We plan (but are not limited to, looking forward to more suggestions from everyone) to provide the following assistance: + +1. Data lake visualization development training based on VisActor helps participating colleagues grow rapidly in programming skills, visualization theory, architecture design and other aspects. +2. Regularly select "Code Contribution Award" and "Community Promotion Award". +3. Organize community members to participate in open source activities diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json index b05b029370..6fe75834e5 100644 --- a/docs/assets/guide/menu.json +++ b/docs/assets/guide/menu.json @@ -22,6 +22,13 @@ "en": "Quick Start" } }, + { + "path": "Contribution_Guide", + "title": { + "zh": "如何加入 VChart 社区", + "en": "How to join the VChart community" + } + }, { "path": "Basic", "title": { diff --git a/docs/assets/guide/zh/tutorial_docs/Contribution_Guide.md b/docs/assets/guide/zh/tutorial_docs/Contribution_Guide.md new file mode 100644 index 0000000000..a45bc44081 --- /dev/null +++ b/docs/assets/guide/zh/tutorial_docs/Contribution_Guide.md @@ -0,0 +1,203 @@ +首先为你选择加入开源贡献行列的行为点赞 👍🏻。再者,十分感谢你选择参与到 VisActor 社区,为这个开源项目做出贡献。 + +## VChart 贡献指南 + +VisActor 团队通常在 github 上进行开发和 issue 维护,请打开 [Github 网站](https://github.com/),点击右上角 `Sign up` 按钮,注册一个自己的账号,开启你开源之旅的第一步。 + +如果因为特殊情况,你无法打开 Github 站点,请告知我们并通过 [Gitee](https://gitee.com/VisActor/VChart) 进行项目开发。 + +在 [VChart 仓库](https://github.com/VisActor/VChart)中,我们有一份面向所有开源贡献者的[指南](https://github.com/VisActor/VChart/blob/develop/CONTRIBUTING.zh-CN.md),介绍了有关版本管理、分支管理等内容,**请花几分钟时间阅读了解一下**。 + +## 你的第一个 Pull Request + +### Step0:安装 Git + +Git 是一种版本控制系统,用于跟踪和管理软件开发项目中的代码变更。它帮助开发者记录和管理代码的历史记录,方便团队协作、代码版本控制、合并代码等操作。通过 Git,您可以追踪每个文件的每个版本,并轻松地在不同版本之间进行切换和比较。Git 还提供了分支管理功能,使得可以同时进行多个并行开发任务。 + +- 访问 Git 官方网站: +- 下载最新版本的 Git 安装程序。 +- 运行下载的安装程序,按照安装向导的提示进行安装。 +- 安装完成后,你可以通过命令行使用 `git version` 命令确认安装成功。 + +### Step1:Fork 项目 + +- 首先需要 fork 这个项目,进入[VChart 项目页面](https://github.com/VisActor/VChart),点击右上角的 Fork 按钮 + +![](/vchart/guide/contribution-guide/fork.PNG) + +- 你的 github 帐号中会出现 xxxx(你的 github 用户名)/vchart 这个项目 +- 在本地电脑上使用以下命令: 得到一个 VChart 文件夹 + +``` +// ssh +git clone git@github.com:xxxx(你的github用户名)/VChart.git +// https +git clone https://github.com/xxxx(你的github用户名)/VChart.git +``` + +### Step2:获取项目代码 + +- 进入 VChart 文件夹,添加 VChart 的远程地址 + +``` +git remote add upstream https://github.com/VisActor/VChart.git +``` + +- 获取 VChart 最新源码 + +``` +git pull upstream develop +``` + +### Step3:创建分支 + +- 好了,现在可以开始贡献我们的代码了。VChart 默认分支为 develop 分支。无论是功能开发、bug 修复、文档编写,都请新建立一个分支,再合并到 develop 分支上。使用以下代码创建分支: + +``` +// 创建功能开发分支 +git checkout -b feat/xxxx + +// 创建问题修复开发分支 +git checkout -b fix/xxxx + +// 创建文档、demo分支 +git checkout -b docs/add-funnel-demo +``` + +假设我们创建了文档修改分支 `docs/add-funnel-demo` + +- 现在我们可以在分支上更改代码了 +- 假设我们已经添加了一些代码,提交到代码库 +- git commit -a -m "docs: add custom funnel demo and related docs" 。VisActor 的 commit 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) 规范 + + - `[optional scope]: ` + - 其中常用的`type`包括 docs(文档、日志修改)、feat(新功能)、fix(问题修复)、refactor(代码重构)等,请根据实际情况选择。 + - 请用简短精确的英文描述编写 description + - 提交 commit 之前,我们会进行 commit lint 检查,具体可以查看[检查规则](https://github.com/VisActor/VChart/blob/98711490e90532d896dd9e44dd00a3af5b95f06d/common/autoinstallers/lint/commitlint.config.js) + +### Step4:合并修改 + +- 一个常见的问题是远程的 upstream (@visactor/vchart) 有了新的更新, 从而会导致我们提交的 Pull Request 时会导致冲突。 因此我们可以在提交前先把远程其他开发者的 commit 和我们的 commit 合并。使用以下代码切换到 develop 分支: + +``` +git checkout develop +``` + +- 使用以下代码拉出远程的最新代码: + +``` +git pull upstream develop +``` + +- 切换回自己的开发分支: + +``` +git checkout docs/add-funnel-demo +``` + +- 把 develop 的 commit 合并到自己分支: + +``` +git rebase develop +``` + +- 把更新代码提交到自己的分支中: + +``` +git push upstream docs/add-funnel-demo +``` + +### Step5:提交 Pull Request + +你可以在你的 github 代码仓库页面点击 `Compare & pull request` 按钮。 + +![](/vchart/guide/contribution-guide/create-PR.png) + +或通过 `contribute` 按钮创建: + +
+ +
+ +按照模板填写本次提交的修改内容: + +- 勾选这是什么类型的修改 +
+ +
+ +- 填写关联的 issue + +
+ +
+ +- 若有复杂变更,请说明背景和解决方案 + +
+ +
+ +相关信息填写完成后,点击 Create pull request 提交。 + +## **轻松步入 VChart 开源贡献之旅** + +"**good first issue**" 是一个在开源社区常见的标签,这个标签的目的是帮助新贡献者找到适合入门的问题。 + +VChart 的入门问题,你可以通过 [issue 列表](https://github.com/VisActor/VChart/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) 查看,目前包括两类: + +- Demo 案例制作 +- 简单功能开发 + +如果你当前**有时间和意愿**参与到社区贡献,可以在 issue 里看一看 **good first issue**,选择一个感兴趣、适合自己的认领。 + +相信你一定是一个有始有终的同学,所以,当你了解并决定认领一个 issue 后,请在 issue 下留言告知大家。 + +### Demo Task 开发指南 + +我们准备了一些在实际应用场景中常见的案例,需要思考如何利用 VChart 的能力实现。 + +你可以通过这类任务,上手对 VChart 的使用。VChart 提供了丰富的能力,每个人或许都有不同的实现思路,**你可以在 issue 下留言,和大家讨论自己的方案**。 + +任务完成后,你可以将自己制作的案例提交到官网 demo,让更多需要的人学习和使用。 + +所有的 demo 存放在 `docs/assets/examples` 目录下 + +1. 请基于 develop 分支,新拉一个 `docs/***`或 `demo/***` 分支进行开发 +2. (如果你已经安装,请跳过此步骤)全局安装 [@microsoft/rush](https://rushjs.io/pages/intro/get_started/):`npm i --global @microsoft/rush` +3. 根目录下运行 `rush update` +4. 运行`rush docs` 在本地预览目前 demo 内容 +5. `docs` 目录下: + 1. `docs/assets/examples/menu.json` 目录文件中添加你的 demo 信息 + 2. 在`zh`/`en`目录下分别完成中英文 demo 文档 + 3. 在 `docs/public/vchart/preview`目录下添加 demo 预览图片并将相对路径更新在 demo 文档中 +6. 提交所有代码,并在 Github 创建 Pull Request,邀请其他人进行 review + +### Feature Task 开发指南 + +我们准备了一些简单、易上手的特性开发任务,如果你有一定的 Javascript / Typescript 基础,可以认领这类任务。 + +你可以通过需求开发,更快地了解 VChart 代码架构。**你可以在 issue 下留言,和大家讨论自己的方案**。 + +1. 请基于 develop 分支,新拉一个 `feat/***`分支进行开发 +2. (如果你已经安装,请跳过此步骤)全局安装 [@microsoft/rush](https://rushjs.io/pages/intro/get_started/):`npm i --global @microsoft/rush` +3. 根目录下运行 `rush update` +4. `rush start` 在本地运行 VChart 代码的测试页面 + - 你可以在`develop/packages/vchart/__tests__/runtime/browser`下创建 index.page.local 页面,引入自己创建的开发用例 +5. 确认所有的测试都是通过的 `rush test` +6. 开发完成后,运行 `rush change` 命令,编写 changelog 并提交 +7. 提交所有代码,并在 Github 创建 Pull Request,邀请其他人进行 review + +## 拥抱 VisActor 社区 + +在你为 VisActor 贡献代码之余,我们鼓励你参与其他让社区更加繁荣的事情,比如: + +1. 为项目的发展、功能规划 等提建议。 +2. 创作文章、视频,开办讲座来宣传 VisActor。 +3. 撰写推广计划,同团队一同执行。 + +VisActor 也在努力帮助参与社区建设的同学一同成长,我们计划(但不限于,期待大家更多的建议)提供如下帮助: + +1. 以 VisActor 为基础的数据可视化研发培训,帮助参与的同学在编程技能、可视化理论、架构设计等多个方面快速成长。 +2. 定期评选“代码贡献奖”和“社区推广奖”。 +3. 组织社区成员参与开源活动。 diff --git a/docs/public/vchart/guide/contribution-guide/create-PR-2.png b/docs/public/vchart/guide/contribution-guide/create-PR-2.png new file mode 100644 index 0000000000..82126a192f Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/create-PR-2.png differ diff --git a/docs/public/vchart/guide/contribution-guide/create-PR.png b/docs/public/vchart/guide/contribution-guide/create-PR.png new file mode 100644 index 0000000000..943c396e85 Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/create-PR.png differ diff --git a/docs/public/vchart/guide/contribution-guide/fork.PNG b/docs/public/vchart/guide/contribution-guide/fork.PNG new file mode 100644 index 0000000000..9b5a2338b6 Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/fork.PNG differ diff --git a/docs/public/vchart/guide/contribution-guide/issue-background.png b/docs/public/vchart/guide/contribution-guide/issue-background.png new file mode 100644 index 0000000000..f3089e353d Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/issue-background.png differ diff --git a/docs/public/vchart/guide/contribution-guide/issue-checklist.png b/docs/public/vchart/guide/contribution-guide/issue-checklist.png new file mode 100644 index 0000000000..52c47c5108 Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/issue-checklist.png differ diff --git a/docs/public/vchart/guide/contribution-guide/related-issue.png b/docs/public/vchart/guide/contribution-guide/related-issue.png new file mode 100644 index 0000000000..e8e0826913 Binary files /dev/null and b/docs/public/vchart/guide/contribution-guide/related-issue.png differ