Add Vitess analysis document #284

dwelsch-esi · 2025-02-19T22:59:50Z

Resolves: #280

deepthi · 2025-02-23T19:22:53Z

analyses/0014-vitess/vitess-analysis.md

+- Advanced > Distributed Atomic Transactions
+- Migration
+
+There is one special-purpose FAQ, for VReplication in the Reference.


We do have this FAQ as well
https://vitess.io/docs/faq/

Ah, OK. It's outside the versioned documentation so I missed it. There's a lot of good information here; I'll have a look and revise the analysis and recommendations!

@deepthi , @frouioui : I've updated the analysis to account fro the FAQ. Apologies for not catching the sections outside the versioned documentation. Please review.

deepthi · 2025-02-23T19:26:06Z

analyses/0014-vitess/vitess-analysis.md

+**Localization & i18n directories**: Are you planning for localization/internationalization
+with regard to site directory structure?
+
+Yes, there are full versions of the documentation in both English and Chinese.


We have been debating removing the Chinese documentation because it is being simply copied over for each new release without any content updates.

@deepthi You mean you're copying a down-level version of the documentation without the updates for new releases? Which version of the documentation is the current Chinese version?

I would recommend keeping it, but maybe stop versioning it, or suggest it's archived or deprecated somehow.

I would recommend keeping it, but maybe stop versioning it, or suggest it's archived or deprecated somehow.

I'd recommend removing it from any release later than the last time it was updated, and redirect from the later releases to that version.

deepthi · 2025-02-23T19:32:57Z

analyses/0014-vitess/vitess-analysis.md

+but it should be presented explicitly as a step in the procedure.
+
+Further down the page, another backup option, *Using mysqlshell*, has the same shortcomings:
+No actual command is presented.


The commands are presented towards the end of the page https://vitess.io/docs/21.0/user-guides/operating-vitess/backup-and-restore/creating-a-backup/
Maybe the page needs to be re-organized.

deepthi · 2025-02-23T19:34:24Z

analyses/0014-vitess/vitess-analysis.md

+path for any problems with a task (the escalation path might be:
+*troubleshooting procedure > Slack Channel > project Issue*). Get rid of the
+[VReplication FAQ](https://vitess.io/docs/21.0/reference/vreplication/faq/)
+in the reference section and put the information in a troubleshooting section.


Would you recommend consolidating everything into https://vitess.io/docs/faq/
And potentially renaming that to Troubleshooting?

@deepthi That's one possibility but there's more than troubleshooting information in the FAQ. See comment above re the FAQ. Let me look into it and I'll add some options to the recommendations.

See recommendations in the analysis. The good news is that there's a lot of good information in the FAQ. The bad news is that it's outside your versioning regimen. Also, I'm not a fan of FAQs in general. I recommend folding the information into the regular technical documentation.

deepthi · 2025-02-23T19:36:35Z

analyses/0014-vitess/vitess-analysis.md

+Yes, there is a Community link in the site’s menu bar, leading to the Community page.
+
+**New contributor document**: Is there a document specifically for new contributors/your
+first contribution?


https://vitess.io/docs/contributing/
That's for code contributions. Should we have a page for docs contributions?

@deepthi Yes, or add doc contribution instructions to the code contribution doc.

chalin · 2025-02-25T17:04:49Z

analyses/0014-vitess/vitess-analysis.md

Rename this file to analyses/0014-vitess/analysis.md

@dwelsch-esi - please also rebase this PR from main at HEAD.

@dwelsch-esi - after you've rebased, also please ensure that all checks are passing.

I've done the rebase @dwelsch-esi & @chalin

(and the file rename)

Might be good to rebase again given the updates that have just landed for the link checking.

Also, could you address the GH check failures?

I just rebased again. I have to go do some mentorship stuff now, but I can check back in on this a bit later.

frouioui · 2025-02-26T14:21:04Z

analyses/0014-vitess/analysis.md

+**Release process**: Does your code release process account for documentation creation
+& updates?
+
+No, neither the [Contribute](https://vitess.io/docs/contributing/) documentation nor
+the [CONTRIBUTING.md](https://github.com/vitessio/vitess/blob/main/CONTRIBUTING.md)
+file in the product repo describes how to contribute documentation. There is no Contribution
+section in the website repo.


We have this tool: https://github.com/vitessio/vitess-releaser, which maintainers use to create and ship new major and patch releases of Vitess. This tool lists and automated steps needed for a release, one of them is related to documentation and guides the maintainer on how to create and update the documentation before and after each release:

https://github.com/vitessio/vitess-releaser/blob/main/go/releaser/release/website_docs.go

@frouioui Does the tool verify that you've updated the release notes?

It does not do this automatically, there is only a step asking the release lead to review them.

What the tool does automate:

The creation of a changelog file that lists all Pull Requests that were merged for this release.

The creation final release notes file, which is a template containing the changelog + a summary file written and reviewed manually by maintainers. This file is later uploaded to the GitHub Release page by the tool.

chalin

See inline comments.

Also, I know that you're still working on this document, but consider addressing the check failures and then keeping the checks passing as the document evolves:

analyses/0014-vitess/analysis.md

chalin · 2025-03-09T13:12:50Z

analyses/0014-vitess/analysis.md

+> ````--topo_implementation=etcd2 --topo_global_server_address=<comma_separated_addresses>
+>   --topo_global_root=/vitess/global
+> ````


This markdown formatting doesn't make sense. First, you can use triple ticks. More importantly, there's probably a newline missing after the code-block opening syntax.

it's also a bit weird because it's a quote. I've gone in and fixed the newline tho.

Adding  as this is quoted content (if it's incorrectly formatted that needs to be communicated).

@dwelsch-esi, could you double check to make sure this snippet is correct from the source.

analyses/0014-vitess/analysis.md

Signed-off-by: Dave Welsch <[email protected]>

Signed-off-by: Nate W <[email protected]>

…ubleshooting. Signed-off-by: Dave Welsch <[email protected]>

Co-authored-by: Patrice Chalin <[email protected]> Signed-off-by: Nate W <[email protected]>

netlify · 2025-03-25T15:23:31Z

✅ Deploy Preview for cncf-techdocs ready!

Name	Link
🔨 Latest commit	`86fc5c9`
🔍 Latest deploy log	https://app.netlify.com/sites/cncf-techdocs/deploys/67e352ff6a1bfa0008aaa64c
😎 Deploy Preview	https://deploy-preview-284--cncf-techdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

… this analyis. Signed-off-by: Nate W <[email protected]>

Signed-off-by: Nate W <[email protected]>

nate-double-u

Let's merge this in as is. We've got issues getting opened over in https://github.com/vitessio/website/issues. We can make updates needed in a follow up PR.

nate-double-u · 2025-04-08T15:19:39Z

Thanks for this @dwelsch-esi, and thanks everyone for the reviews.

nate-double-u mentioned this pull request Feb 21, 2025

Update doc analysis criteria #286

Merged

deepthi reviewed Feb 23, 2025

View reviewed changes

chalin requested changes Feb 25, 2025

View reviewed changes

frouioui reviewed Feb 26, 2025

View reviewed changes

chalin changed the title ~~Add Vitess analysis document.~~ Add Vitess analysis document Mar 9, 2025

chalin requested changes Mar 9, 2025

View reviewed changes

dwelsch-esi and others added 7 commits March 17, 2025 14:03

Add Vitess analysis document.

ce9648d

Signed-off-by: Dave Welsch <[email protected]>

renaming file

0bab389

Signed-off-by: Nate W <[email protected]>

fixing formatting issues

7d011d1

Signed-off-by: Nate W <[email protected]>

fixing formatting issues

a2b1ead

Signed-off-by: Nate W <[email protected]>

Update per review comments, including recommendations for FAQ and tro…

763d282

…ubleshooting. Signed-off-by: Dave Welsch <[email protected]>

Update analyses/0014-vitess/analysis.md

9b0d752

Co-authored-by: Patrice Chalin <[email protected]> Signed-off-by: Nate W <[email protected]>

Update analyses/0014-vitess/analysis.md

3748196

Co-authored-by: Patrice Chalin <[email protected]> Signed-off-by: Nate W <[email protected]>

chalin force-pushed the main branch from 24d9a76 to 3748196 Compare March 17, 2025 18:03

Merge branch 'main' into main

71e7e2b

nate-double-u added 7 commits March 25, 2025 17:35

removing SEO, Analytics and local search sections as out of scope for…

dc83ade

… this analyis. Signed-off-by: Nate W <[email protected]>

updating spelling wordlist

bf10dc6

Signed-off-by: Nate W <[email protected]>

fixing format

c899886

Signed-off-by: Nate W <[email protected]>

removing markdown disable no-bare-urls

6bc4fa6

Signed-off-by: Nate W <[email protected]>

updating codefence formatting

74d8787

Signed-off-by: Nate W <[email protected]>

disabling fence-code-langage check on quoted content

94dc35b

Signed-off-by: Nate W <[email protected]>

fixing formatting

86fc5c9

Signed-off-by: Nate W <[email protected]>

nate-double-u requested a review from chalin March 26, 2025 01:08

nate-double-u approved these changes Apr 8, 2025

View reviewed changes

nate-double-u enabled auto-merge (squash) April 8, 2025 15:19

nate-double-u disabled auto-merge April 8, 2025 15:21

nate-double-u merged commit 77d8246 into cncf:main Apr 8, 2025
9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add Vitess analysis document #284

Add Vitess analysis document #284

dwelsch-esi commented Feb 19, 2025 •

edited by nate-double-u

Loading

deepthi Feb 23, 2025

dwelsch-esi Feb 25, 2025

dwelsch-esi Mar 6, 2025

deepthi Feb 23, 2025

dwelsch-esi Feb 25, 2025

nate-double-u Feb 25, 2025

dwelsch-esi Mar 5, 2025

deepthi Feb 23, 2025

deepthi Feb 23, 2025

dwelsch-esi Feb 25, 2025

dwelsch-esi Mar 6, 2025

deepthi Feb 23, 2025

dwelsch-esi Feb 25, 2025

chalin Feb 25, 2025

chalin Feb 25, 2025

chalin Feb 25, 2025

nate-double-u Feb 25, 2025

nate-double-u Feb 25, 2025

chalin Feb 25, 2025

chalin Feb 25, 2025

nate-double-u Feb 25, 2025

frouioui Feb 26, 2025

dwelsch-esi Mar 6, 2025

frouioui Mar 12, 2025

chalin left a comment

chalin Mar 9, 2025

nate-double-u Mar 26, 2025

nate-double-u Mar 26, 2025

netlify bot commented Mar 25, 2025 •

edited

Loading

nate-double-u left a comment

nate-double-u commented Apr 8, 2025

Add Vitess analysis document #284

Add Vitess analysis document #284

Conversation

dwelsch-esi commented Feb 19, 2025 • edited by nate-double-u 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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chalin 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

netlify bot commented Mar 25, 2025 • edited Loading

✅ Deploy Preview for cncf-techdocs ready!

nate-double-u left a comment

Choose a reason for hiding this comment

nate-double-u commented Apr 8, 2025

dwelsch-esi commented Feb 19, 2025 •

edited by nate-double-u

Loading

netlify bot commented Mar 25, 2025 •

edited

Loading