fix: all link broken and enable Version-Awareness in README and README-Cn #2476

yihong0618 · 2021-05-17T03:14:22Z

What changes were proposed in this pull request?

Fix link broken in README and README-CN
Add version-awareness highlights and background information to new comers
I've run the tests to see all new and existing tests pass
If this Pull Request resolves an issue, I linked to the issue in the text above
I've informed the technical writer about the documentation change if necessary

CLAassistant · 2021-05-17T03:14:27Z

All committers have signed the CLA.

wey-gu · 2021-05-17T03:53:29Z

A little bit background here that this repo is actually for v1.0.* nebula graph when it's monorepo.
When we started the v2.0.*, in multiple repo, it was done in different repos as nebula-graph, nebula-common, nebula-storage.

We should polish and highlight enough information here to:

Ensure links for both v1.0 and v2.0 are properly navigated
Reflect and highlight the above backgrounds to avoid confusion

Are you interested in/with bandwidth to address it? Or I could co-author this PR for that.

yihong0618 · 2021-05-17T03:59:30Z

@wey-gu
Got your point. I think it's better to help me to finish the PR, because I have little background about it.

I found the v1.2 version in the doc

Can we info users that

If you want to use v1.* link --> https://docs.nebula-graph.io/1.2.0/manual-EN/1.overview/2.quick-start/1.get-started/

Somethin like this.

wey-gu · 2021-05-17T04:02:37Z

@wey-gu
Got your point. I think it's better to help me to finish the PR, because I have little background about it.

I found the v1.2 version in the doc

Can we info users that

If you want to use v1.* link --> https://docs.nebula-graph.io/1.2.0/manual-EN/1.overview/2.quick-start/1.get-started/

Somethin like this.

Sure, let's do it together.

For :

Can we info users that

If you want to use v1.* link --> https://docs.nebula-graph.io/1.2.0/manual-EN/1.overview/2.quick-start/1.get-started/

Somethin like this.

That's also the way in my head, could you try from your side first then I'll try to fill my part on this PR?

Thanks!!

yihong0618 · 2021-05-17T04:50:23Z

@wey-gu
Done~

jamieliu1023 · 2021-05-18T02:02:52Z

CONTRIBUTING.md

@@ -1,3 +1,3 @@
 # CONTRIBUTING

-See [How to contribute](https://docs.nebula-graph.io/manual-EN/4.contributions/how-to-contribute/) for details about how to contribute to **Nebula Graph**.
+See [How to contribute](https://docs.nebula-graph.io/2.0.1/15.contribution/how-to-contribute/) for details about how to contribute to **Nebula Graph**.


I personally don't think it is a good idea to add a link with version number because new versions come out from time to time, meaning that you have to update the link from time to time.
We have a how-to-contribute file in the nebula-community repo and here is the link: https://github.com/vesoft-inc/nebula-community/blob/master/Contributors/how-to-contribute.md. I think this is a better choice.

Agreed, this is a better choice, will replace it with this link instead.

jamieliu1023 · 2021-05-18T02:03:49Z

README-CN.md

 ## 快速使用

-请查看[快速使用手册](https://docs.nebula-graph.com.cn/manual-CN/4.contributions/how-to-contribute/)，开始使用 **Nebula Graph**。
+请查看[快速使用手册](https://docs.nebula-graph.com.cn/2.0.1/2.quick-start/1.quick-start-workflow/)，开始使用 **Nebula Graph**。


Since this is the repo of Nebula v1.x, should we just place the Quick Start of v1.0?

For Quick Start Part, it's actually only applied to newcomers here, when the latest version makes more sense to them, and for those who (for some reason, which I consider can barely be the case) actually would like to access the Quick Start for the old version 1, it's also highlighted in the *note* part.

What do you think about this perspective?

I think now the nebula repo somehow becomes the first impression entry that accidentally being accessed by first-comers, in a not small chance(it was an expected first impression with a decent amount of stars, right?).

It's more than it is on README for version 1 nebula graph. Thus it may be better to highlight contexts around a. version & hey, this is the old one, and b. ensure navigations are valid as the first impression of a project.

There will be a lot of maintenance work if you put the link to the "latest" version here because the "latest" version changes over time. What about when the v3.x comes out? You will have to keep updating the link here, which is a tedious work to do. My point here is that we put the exact version of Quick Start here and keep visitors informed that this is the 1.x version of Nebula Graph and head to the nebula-graph repo if you are interested in a higher version. Let's keep things clear and simple. What do you think?

@jamieliu1023 @wey-gu
I think the better idea is not to add the latest version in the URL.

The doc pointer always points to the latest version.

but users can select the other versions

Something like below.
https://pytorch.org/docs/stable/backends.html
https://zh-hans.reactjs.org/versions/

@jamieliu1023 @wey-gu
I think the better idea is not to add the latest version in the URL.

The doc pointer always points to the latest version.

but users can select the other versions

Something like below.
https://pytorch.org/docs/stable/backends.html
https://zh-hans.reactjs.org/versions/

I agree with the latest aliases(it's also what's in my head these days, not cheating) ;-).
I will recommend/issue it to the docs, there is such a thing already on the tooling we are using.
https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#publishing-a-new-version

Update: ISSUE: vesoft-inc/nebula-docs-cn#462

There will be a lot of maintenance work if you put the link to the "latest" version here because the "latest" version changes over time. What about when the v3.x comes out? You will have to keep updating the link here, which is a tedious work to do. My point here is that we put the exact version of Quick Start here and keep visitors informed that this is the 1.x version of Nebula Graph and head to the nebula-graph repo if you are interested in a higher version. Let's keep things clear and simple. What do you think?

I agree with your concerns, maybe let's see if we can have the "latest" alias in a short time soon on vesoft-inc/nebula-docs-cn#462

jamieliu1023 · 2021-05-18T02:05:08Z

README-CN.md

-请查看[快速使用手册](https://docs.nebula-graph.com.cn/manual-CN/4.contributions/how-to-contribute/)，开始使用 **Nebula Graph**。
+请查看[快速使用手册](https://docs.nebula-graph.com.cn/2.0.1/2.quick-start/1.quick-start-workflow/)，开始使用 **Nebula Graph**。
+
+在开始使用 **Nebula Graph** 之前，必须通过[编译源码](https://docs.nebula-graph.com.cn/2.0.1/4.deployment-and-installation/2.compile-and-install-nebula-graph/1.install-nebula-graph-by-compiling-the-source-code/)，[rpm/deb 包](https://docs.nebula-graph.com.cn/2.0.1/4.deployment-and-installation/2.compile-and-install-nebula-graph/2.install-nebula-graph-by-rpm-or-deb/) 或者 [docker compose](https://github.com/vesoft-inc/nebula-docker-compose/blob/master/README_zh-CN.md) 方式安装 **Nebula Graph**。您也可以观看[视频](https://space.bilibili.com/472621355)学习如何安装 **Nebula Graph**。


Same here. Should we use the documentation of v1.0?

jamieliu1023 · 2021-05-18T02:06:10Z

README-CN.md

@@ -81,7 +95,7 @@
 **Nebula Graph** 是一个完全开源的项目，欢迎开源爱好者通过以下方式参与到 **Nebula Graph** 社区：

 * 从标记为 [good first issues](https://github.com/vesoft-inc/nebula/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 的问题入手
-* 贡献代码，详情请参见 [如何贡献](https://docs.nebula-graph.com.cn/manual-CN/4.contributions/how-to-contribute/)
+* 贡献代码，详情请参见 [如何贡献](https://docs.nebula-graph.com.cn/2.0.1/15.contribution/how-to-contribute/)


Same as the previous comment about the how-to-contribute file.

Co-authored-by: Jamie-VESoft <[email protected]>

wey-gu · 2021-05-20T02:51:55Z

Dear @cooper-lzy @randomJoe211 ,
Could you please help review this? Thanks!

cooper-lzy · 2021-05-20T03:03:39Z

README-CN.md

@@ -41,11 +41,25 @@

 [Nebula Graph Cloud Service](https://cloud.nebula-graph.com.cn/) 是 Nebula Graph 的图数据库云服务平台（Database-as-a-Service，DBaaS），支持一键部署 Nebula Graph。Nebula Graph Cloud Service 服务目前处于公测阶段。公测期间不会就云服务收取任何费用，欢迎 **免费试用**。

+## 关于这个 Repo
+
+Please note that this repo is only for Nebula Graph `v1.*.*`.


这里应该是中文：本仓库为Nebula Graph 1.x，最新的Nebula Graph 2.x已拆分为nebula-graph、nebula-storage和nebula-common三个仓库。

sorry，我傻了，居然留了英文那句，多谢！

cooper-lzy · 2021-05-20T03:06:14Z

README-CN.md

 ## 快速使用

-请查看[快速使用手册](https://docs.nebula-graph.com.cn/manual-CN/4.contributions/how-to-contribute/)，开始使用 **Nebula Graph**。
+请查看[文档](https://docs.nebula-graph.com.cn)中的【快速使用手册】，开始使用 **Nebula Graph**。


这里可以直接链接到快速入门流程 https://docs.nebula-graph.com.cn/2.0.1/2.quick-start/1.quick-start-workflow/

好的，我看您留了 master 的链接，这是一个好办法。

randomJoe211

Great!

randomJoe211 · 2021-05-20T03:17:19Z

README-CN.md

@@ -41,11 +41,25 @@

 [Nebula Graph Cloud Service](https://cloud.nebula-graph.com.cn/) 是 Nebula Graph 的图数据库云服务平台（Database-as-a-Service，DBaaS），支持一键部署 Nebula Graph。Nebula Graph Cloud Service 服务目前处于公测阶段。公测期间不会就云服务收取任何费用，欢迎 **免费试用**。

+## 关于这个 Repo


Maybe move this section to the start of the topic. This should be the first thing that a reader needs to know.
So does in the English version.

Agreed, will do so.

randomJoe211 · 2021-05-20T03:21:52Z

README-CN.md

-请查看[快速使用手册](https://docs.nebula-graph.com.cn/manual-CN/4.contributions/how-to-contribute/)，开始使用 **Nebula Graph**。
+请查看[文档](https://docs.nebula-graph.com.cn)中的【快速使用手册】，开始使用 **Nebula Graph**。
+
+在开始使用 **Nebula Graph** 之前，除了参文档通过：编译源码、rpm/deb 包、 docker compose 三者之一方式安装 **Nebula Graph**。您也可以观看[视频](https://space.bilibili.com/472621355)学习如何安装 **Nebula Graph**。


“在开始使用 Nebula Graph 之前，除了参文档通过：编译源码、rpm/deb 包、 docker compose 三者之一方式安装 Nebula Graph。您也可以观看视频学习如何安装 Nebula Graph。”
==>
“除了参考文档，您也可以观看[视频]了解如何安装xxxx。”

randomJoe211 · 2021-05-20T03:22:47Z

README-CN.md


-在开始使用 **Nebula Graph** 之前，必须通过[编译源码](https://docs.nebula-graph.com.cn/manual-CN/3.build-develop-and-administration/1.build/1.build-source-code/)，[rpm/deb 包](https://docs.nebula-graph.com.cn/manual-CN/3.build-develop-and-administration/2.install/1.install-with-rpm-deb/) 或者 [docker compose](https://github.com/vesoft-inc/nebula-docker-compose/blob/master/README_zh-CN.md) 方式安装 **Nebula Graph**。您也可以观看[视频](https://space.bilibili.com/472621355)学习如何安装 **Nebula Graph**。
+**注意**


注意：

randomJoe211 · 2021-05-20T03:50:56Z

README-CN.md

+- [Getting started](https://docs.nebula-graph.com.cn/1.2.0/manual-CN/1.overview/2.quick-start/1.get-started/)
+- [installing source code](https://docs.nebula-graph.com.cn/1.2.0/manual-CN/3.build-develop-and-administration/1.build/1.build-source-code/)
+- [rpm/deb packages](https://docs.nebula-graph.com.cn/1.2.0/manual-CN/3.build-develop-and-administration/2.install/1.install-with-rpm-deb/)


1.2.1 is the latest version

randomJoe211 · 2021-05-20T03:53:18Z

README.md

+
+Please note that this repo is only for Nebula Graph `v1.*.*`.
+
+From `v2.*.*`, which was already GA in 2021 April, Nebula Graph's core code bases are [nebula-graph](https://github.com/vesoft-inc/nebula-graph), [nebula-common](https://github.com/vesoft-inc/nebula-common) and [nebula-storage](https://github.com/vesoft-inc/nebula-storage), it's recommended to start from the repo: [nebula-graph](https://github.com/vesoft-inc/nebula-graph).


the GA version of which has already been released in April 2021,

Codebase is more popular to programmers than code base.

randomJoe211 · 2021-05-20T03:55:26Z

README.md


-Please note that you must install **Nebula Graph** by [installing source code](https://docs.nebula-graph.io/manual-EN/3.build-develop-and-administration/1.build/1.build-source-code/), [rpm/deb packages](https://docs.nebula-graph.io/manual-EN/3.build-develop-and-administration/2.install/1.install-with-rpm-deb/) or [docker compose](https://github.com/vesoft-inc/nebula-docker-compose), before you can actually start using it. If you prefer a video tutorial, visit our [YouTube channel](https://www.youtube.com/channel/UC73V8q795eSEMxDX4Pvdwmw).
+For Nebula Graph Installation, in addition to referring to the docs to deploy from one of the three options: source code, RPM/DEB package, or Docker Compose, if you prefer a video tutorial, please check out our [YouTube channel](https://www.youtube.com/channel/UC73V8q795eSEMxDX4Pvdwmw).


installation

Optimize this paragraph according to the comment for the Chinese version?

sure, will do so.

wey-gu · 2021-05-20T08:18:41Z

All comments fix done. If review passed this time I will trigger a CI/TEST.
@cooper-lzy @randomJoe211 kindly help review when available :-), thanks!

codecov-commenter · 2021-05-24T09:25:58Z

Codecov Report

Merging #2476 (f24d7db) into master (2249c03) will decrease coverage by 0.18%.
The diff coverage is 82.87%.

@@            Coverage Diff             @@
##           master    #2476      +/-   ##
==========================================
- Coverage   86.46%   86.28%   -0.19%     
==========================================
  Files         649      647       -2     
  Lines       64374    67278    +2904     
==========================================
+ Hits        55662    58048    +2386     
- Misses       8712     9230     +518

Impacted Files	Coverage Δ
src/common/base/EitherOr.h	`95.69% <ø> (ø)`
src/common/base/StatusOr.h	`91.85% <ø> (ø)`
src/common/filter/geo/GeoParams.h	`100.00% <ø> (ø)`
src/common/fs/FileUtils.h	`85.71% <ø> (ø)`
src/common/hdfs/HdfsCommandHelper.cpp	`0.00% <0.00%> (-75.00%)`	⬇️
src/common/stats/StatsManager.h	`100.00% <ø> (ø)`
src/common/time/Duration.cpp	`75.86% <ø> (ø)`
src/common/time/Duration.h	`100.00% <ø> (ø)`
src/common/time/detail/TscHelper.cpp	`100.00% <ø> (ø)`
src/common/utils/NebulaKeyUtils.cpp	`92.16% <0.00%> (-5.29%)`	⬇️
... and 160 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 721ae51...f24d7db. Read the comment docs.

wey-gu · 2021-05-25T07:15:09Z

It seems there are issues in CLANG test, could we bypass/fix it? @CPWstatic

…E-Cn (vesoft-inc#2476) * fix: all link broken in README and README-Cn * fix: note links for v1.* * Version awareness links and notices added * Addressed the how-to links to community repo instead Co-authored-by: Jamie-VESoft <[email protected]> * Removed 2.* URLs before we have a Latest Alias on Docs * fixed how-to-contribute link * Update README-CN.md * Address Joe's comments * Update README-CN.md Co-authored-by: wey-gu <[email protected]> Co-authored-by: Jamie-VESoft <[email protected]> Co-authored-by: cooper-lzy <[email protected]>

fix: all link broken in README and README-Cn

ca1263c

wey-gu changed the title ~~fix: all link broken in README and README-Cn~~ fix: all link broken and enable Version-Awareness in README and README-Cn May 17, 2021

fix: note links for v1.*

470c61e

Version awareness links and notices added

90b2b2d

wey-gu requested review from jamieliu1023, dutor and laura-ding May 17, 2021 05:43

jamieliu1023 reviewed May 18, 2021

View reviewed changes

Addressed the how-to links to community repo instead

849abaf

Co-authored-by: Jamie-VESoft <[email protected]>

wey-gu requested a review from jamieliu1023 May 18, 2021 02:26

wey-gu mentioned this pull request May 19, 2021

Add latest alias for versioned URLs vesoft-inc/nebula-docs-cn#462

Closed

wey-gu added 2 commits May 20, 2021 10:26

Removed 2.* URLs before we have a Latest Alias on Docs

142d6be

fixed how-to-contribute link

9c645de

wey-gu requested review from cooper-lzy and randomJoe211 May 20, 2021 02:51

Update README-CN.md

50cdd09

cooper-lzy previously approved these changes May 20, 2021

View reviewed changes

randomJoe211 reviewed May 20, 2021

View reviewed changes

Address Joe's comments

e9c33ab

wey-gu dismissed cooper-lzy’s stale review via e9c33ab May 20, 2021 08:16

wey-gu requested a review from randomJoe211 May 20, 2021 08:17

wey-gu requested a review from cooper-lzy May 20, 2021 08:17

Update README-CN.md

f24d7db

cooper-lzy approved these changes May 24, 2021

View reviewed changes

randomJoe211 approved these changes May 24, 2021

View reviewed changes

CPWstatic added the ready-for-testing PR: ready for the CI test label May 24, 2021

CPWstatic merged commit 2faf9bd into vesoft-inc:master May 25, 2021

yihong0618 mentioned this pull request Mar 21, 2023

开源四年的一些记录 yihong0618/gitblog#259

Open

		@@ -41,11 +41,25 @@

		[Nebula Graph Cloud Service](https://cloud.nebula-graph.com.cn/) 是 Nebula Graph 的图数据库云服务平台（Database-as-a-Service，DBaaS），支持一键部署 Nebula Graph。Nebula Graph Cloud Service 服务目前处于公测阶段。公测期间不会就云服务收取任何费用，欢迎免费试用。

		## 关于这个 Repo


		在开始使用 Nebula Graph 之前，必须通过[编译源码](https://docs.nebula-graph.com.cn/manual-CN/3.build-develop-and-administration/1.build/1.build-source-code/)，[rpm/deb 包](https://docs.nebula-graph.com.cn/manual-CN/3.build-develop-and-administration/2.install/1.install-with-rpm-deb/) 或者 [docker compose](https://github.com/vesoft-inc/nebula-docker-compose/blob/master/README_zh-CN.md) 方式安装 Nebula Graph。您也可以观看[视频](https://space.bilibili.com/472621355)学习如何安装 Nebula Graph。
		注意


		Please note that this repo is only for Nebula Graph `v1..`.

		From `v2..`, which was already GA in 2021 April, Nebula Graph's core code bases are [nebula-graph](https://github.com/vesoft-inc/nebula-graph), [nebula-common](https://github.com/vesoft-inc/nebula-common) and [nebula-storage](https://github.com/vesoft-inc/nebula-storage), it's recommended to start from the repo: [nebula-graph](https://github.com/vesoft-inc/nebula-graph).


		Please note that you must install Nebula Graph by [installing source code](https://docs.nebula-graph.io/manual-EN/3.build-develop-and-administration/1.build/1.build-source-code/), [rpm/deb packages](https://docs.nebula-graph.io/manual-EN/3.build-develop-and-administration/2.install/1.install-with-rpm-deb/) or [docker compose](https://github.com/vesoft-inc/nebula-docker-compose), before you can actually start using it. If you prefer a video tutorial, visit our [YouTube channel](https://www.youtube.com/channel/UC73V8q795eSEMxDX4Pvdwmw).
		For Nebula Graph Installation, in addition to referring to the docs to deploy from one of the three options: source code, RPM/DEB package, or Docker Compose, if you prefer a video tutorial, please check out our [YouTube channel](https://www.youtube.com/channel/UC73V8q795eSEMxDX4Pvdwmw).

fix: all link broken and enable Version-Awareness in README and README-Cn #2476

fix: all link broken and enable Version-Awareness in README and README-Cn #2476

Conversation

yihong0618 commented May 17, 2021 • edited by wey-gu Loading

What changes were proposed in this pull request?

CLAassistant commented May 17, 2021 • edited Loading

wey-gu commented May 17, 2021

yihong0618 commented May 17, 2021 • edited Loading

wey-gu commented May 17, 2021

yihong0618 commented May 17, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

yihong0618 May 19, 2021 • edited Loading

Choose a reason for hiding this comment

wey-gu May 19, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wey-gu commented May 20, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

randomJoe211 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

randomJoe211 May 20, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wey-gu commented May 20, 2021 • edited Loading

codecov-commenter commented May 24, 2021 • edited Loading

Codecov Report

wey-gu commented May 25, 2021

yihong0618 commented May 17, 2021 •

edited by wey-gu

Loading

CLAassistant commented May 17, 2021 •

edited

Loading

yihong0618 commented May 17, 2021 •

edited

Loading

yihong0618 May 19, 2021 •

edited

Loading

wey-gu May 19, 2021 •

edited

Loading

randomJoe211 May 20, 2021 •

edited

Loading

wey-gu commented May 20, 2021 •

edited

Loading

codecov-commenter commented May 24, 2021 •

edited

Loading