From 2cad70364e28894c79b2921147bc9f5e00372299 Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sat, 14 Dec 2024 22:06:43 +0100 Subject: [PATCH 1/7] Use single target for all binaries Signed-off-by: Rohit Nayak --- Makefile | 115 +++++++++---------------------------------------------- 1 file changed, 19 insertions(+), 96 deletions(-) diff --git a/Makefile b/Makefile index 6abe2a447..f37881f70 100644 --- a/Makefile +++ b/Makefile @@ -42,101 +42,24 @@ check-all-links: clean build link-checker-setup bin/htmltest --conf .htmltest.external.yml ifndef COBRADOC_VERSION_PAIRS -export COBRADOC_VERSION_PAIRS="main:22.0,v21.0.0:21.0,v20.0.3:20.0,v19.0.7:19.0,v18.0.8:18.0" +export COBRADOC_VERSION_PAIRS="main:22.0,v21.0.0:21.0,v20.0.3:20.0,v19.0.7:19.0" endif -generated-docs: mysqlctl-docs \ - mysqlctld-docs \ - topo2topo-docs \ - vtaclcheck-docs \ - vtbackup-docs \ - vtbench-docs \ - vtclient-docs \ - vtcombo-docs \ - vtctld-docs \ - vtctldclient-docs \ - vtgate-docs \ - vtgateclienttest-docs \ - vtorc-docs \ - vttablet-docs \ - vttestserver-docs \ - vttlstest-docs \ - zk-docs \ - zkctl-docs \ - zkctld-docs - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make mysqlctl-docs -mysqlctl-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" mysqlctl - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make mysqlctld-docs -mysqlctld-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" mysqlctld - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtaclcheck-docs -vtaclcheck-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtaclcheck - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make topo2topo-docs -topo2topo-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" topo2topo - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtbackup-docs -vtbackup-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtbackup - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtbench-docs -vtbench-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtbench - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtclient-docs -vtclient-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtclient - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtcombo-docs -vtcombo-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtcombo - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtctld-docs -vtctld-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtctld - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtctldclient-docs -vtctldclient-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtctldclient - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtgate-docs -vtgate-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtgate - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtgateclienttest-docs -vtgateclienttest-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtgateclienttest - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vtorc-docs -vtorc-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vtorc - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vttablet-docs -vttablet-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vttablet - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vttestserver-docs -vttestserver-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vttestserver - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make vttlstest-docs -vttlstest-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" vttlstest - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make zk-docs -zk-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" zk - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make zkctl-docs -zkctl-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" zkctl - -# Usage: VITESS_DIR=/full/path/to/vitess.io/vitess make zkctld-docs -zkctld-docs: - go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" zkctld +BINS := mysqlctl mysqlctld vtaclcheck topo2topo vtbackup vtclient vtcombo \ + vtctld vtctldclient vtgate vtgateclienttest vtorc vttablet vttestserver \ + vttlstest zk zkctl zkctld + +# Pattern rule for building docs for a single binary. +# Running `make mysqlctl-docs` will trigger this rule, for example. +# VITESS_DIR should be specified as an environment variable, pointing to the root of the local Vitess repository +# with most recent code and all release branches fetched, for which the docs are being generated. +# Example, to make all current release versions: +# `make mysqlctl-docs VITESS_DIR=~/go/src/github.com/vitessio/vitess` +# For a specific version, you can specify COBRADOC_VERSION_PAIRS as an environment variable, Example: +# `make mysqlctl-docs COBRADOC_VERSION_PAIRS="main:22.0" VITESS_DIR=~/go/src/github.com/vitessio/vitess` +%-docs: + go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" $(patsubst %-docs,%,$@) + +# Target to run them all. +.PHONY: generated-docs +generated-docs: $(BINS:%=%-docs) From 6d76aeda7fb3e4a0d5a996904f147f14e418f0ea Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sat, 14 Dec 2024 23:13:39 +0100 Subject: [PATCH 2/7] add debugging output for docgen runs: needed this to identify failures in the tool Signed-off-by: Rohit Nayak --- tools/cobradocs/version.go | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/tools/cobradocs/version.go b/tools/cobradocs/version.go index 5542b8045..b095427ec 100644 --- a/tools/cobradocs/version.go +++ b/tools/cobradocs/version.go @@ -78,9 +78,11 @@ func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath strin docgen := exec.Command("go", "run", docgenPath, "-d", v.Dir(workdir)) debugf(docgen.String()) - if err = docgen.Run(); err != nil { + var output []byte + if output, err = docgen.CombinedOutput(); err != nil { return err } + debugf("docgen output: %s", output) return err } From 04b14c123eb0f0f88ce02f371471602a92b4d744 Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sat, 14 Dec 2024 23:38:15 +0100 Subject: [PATCH 3/7] Commit updated files as part of make target Signed-off-by: Rohit Nayak --- Makefile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Makefile b/Makefile index f37881f70..9b2e083fc 100644 --- a/Makefile +++ b/Makefile @@ -59,6 +59,8 @@ BINS := mysqlctl mysqlctld vtaclcheck topo2topo vtbackup vtclient vtcombo \ # `make mysqlctl-docs COBRADOC_VERSION_PAIRS="main:22.0" VITESS_DIR=~/go/src/github.com/vitessio/vitess` %-docs: go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" $(patsubst %-docs,%,$@) + COMMIT_HASH=$(shell cd $(VITESS_DIR) && git rev-parse --short HEAD) && \ + git add -u content && git commit -s -m "Update cobradocs for $$COMMIT_HASH" # Target to run them all. .PHONY: generated-docs From 33fa661dc342f3d5570df5403e0a0afc6e0cd0b1 Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sat, 14 Dec 2024 23:45:07 +0100 Subject: [PATCH 4/7] Add binary to the commit message Signed-off-by: Rohit Nayak --- Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Makefile b/Makefile index 9b2e083fc..d025697f9 100644 --- a/Makefile +++ b/Makefile @@ -60,7 +60,7 @@ BINS := mysqlctl mysqlctld vtaclcheck topo2topo vtbackup vtclient vtcombo \ %-docs: go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" $(patsubst %-docs,%,$@) COMMIT_HASH=$(shell cd $(VITESS_DIR) && git rev-parse --short HEAD) && \ - git add -u content && git commit -s -m "Update cobradocs for $$COMMIT_HASH" + git add -u content && git commit -s -m "Update cobradocs for $$COMMIT_HASH for $(patsubst %-docs,%,$@)" # Target to run them all. .PHONY: generated-docs From e9153e0bd4946bf8e4f0a0145aabf5e192a48303 Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sun, 15 Dec 2024 15:03:19 +0100 Subject: [PATCH 5/7] Add more debug messages Signed-off-by: Rohit Nayak --- tools/cobradocs/version.go | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/tools/cobradocs/version.go b/tools/cobradocs/version.go index b095427ec..ef896bf55 100644 --- a/tools/cobradocs/version.go +++ b/tools/cobradocs/version.go @@ -40,28 +40,26 @@ func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath strin } defer func() { - debugf("chdir %s", workdir) + debugf("in defer: chdir %s", workdir) if cderr := os.Chdir(workdir); cderr != nil { if err == nil { err = cderr } } }() - if v.Ref != "HEAD" { gitCheckout := exec.Command("git", "checkout", v.Ref) - debugf(gitCheckout.String()) - if err = gitCheckout.Run(); err != nil { + if output, err := gitCheckout.CombinedOutput(); err != nil { + debugf("output: %s, err: %s", output, err) return err } - defer func() { gitCheckout := exec.Command("git", "checkout", "-") - debugf(gitCheckout.String()) - if checkoutErr := gitCheckout.Run(); checkoutErr != nil { + if output, checkoutErr := gitCheckout.CombinedOutput(); checkoutErr != nil { if err == nil { err = checkoutErr } + debugf("output: %s, err: %s", output, checkoutErr) } }() } @@ -80,9 +78,9 @@ func (v version) GenerateDocs(workdir string, vitessDir string, docgenPath strin debugf(docgen.String()) var output []byte if output, err = docgen.CombinedOutput(); err != nil { + debugf("docgen output: %s, err %s", output, err) return err } debugf("docgen output: %s", output) - return err } From eb43dfe4c6f5703da5981a5aa68c51feade17117 Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Sun, 15 Dec 2024 15:31:03 +0100 Subject: [PATCH 6/7] Don't try to commit if there are no files. Otherwise we get a spurious empty commit for each binary Signed-off-by: Rohit Nayak --- Makefile | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Makefile b/Makefile index d025697f9..d049c4f52 100644 --- a/Makefile +++ b/Makefile @@ -59,8 +59,11 @@ BINS := mysqlctl mysqlctld vtaclcheck topo2topo vtbackup vtclient vtcombo \ # `make mysqlctl-docs COBRADOC_VERSION_PAIRS="main:22.0" VITESS_DIR=~/go/src/github.com/vitessio/vitess` %-docs: go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" $(patsubst %-docs,%,$@) - COMMIT_HASH=$(shell cd $(VITESS_DIR) && git rev-parse --short HEAD) && \ - git add -u content && git commit -s -m "Update cobradocs for $$COMMIT_HASH for $(patsubst %-docs,%,$@)" + COMMIT_HASH=$(shell cd $(VITESS_DIR) && git rev-parse --short HEAD); \ + git add -u content && \ + if ! git diff --cached --quiet HEAD --; then \ + git commit -s -m "Update cobradocs for $$COMMIT_HASH for $(patsubst %-docs,%,$@)"; \ + fi # Target to run them all. .PHONY: generated-docs From 01e7df9b1fa54098ef8a954ac1a48a0a2fddddcf Mon Sep 17 00:00:00 2001 From: Rohit Nayak Date: Tue, 7 Jan 2025 10:57:00 +0100 Subject: [PATCH 7/7] set -x to show what's going on. Alert if wrong go version. Delete -e files explicitly. Commit changed files Signed-off-by: Rohit Nayak --- Makefile | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/Makefile b/Makefile index d049c4f52..c522610c7 100644 --- a/Makefile +++ b/Makefile @@ -58,7 +58,24 @@ BINS := mysqlctl mysqlctld vtaclcheck topo2topo vtbackup vtclient vtcombo \ # For a specific version, you can specify COBRADOC_VERSION_PAIRS as an environment variable, Example: # `make mysqlctl-docs COBRADOC_VERSION_PAIRS="main:22.0" VITESS_DIR=~/go/src/github.com/vitessio/vitess` %-docs: + set -x + @if echo "$$COBRADOC_VERSION_PAIRS" | grep -qE '20\.0|19\.0'; then \ + if [ "$${GOROOT##*/}" != "go1.21" ]; then \ + echo "Error: Go 1.21 is required when COBRADOC_VERSION_PAIRS contains 20.0 or 19.0."; \ + echo "Current GOROOT is: $$GOROOT"; \ + exit 1; \ + fi; \ + fi go run ./tools/cobradocs/ --vitess-dir "${VITESS_DIR}" --version-pairs "${COBRADOC_VERSION_PAIRS}" $(patsubst %-docs,%,$@) + find . -name "*md-e" -exec rm {} \; + @CHANGED_FILES=$$(git diff --name-only) && \ + if [ -n "$$CHANGED_FILES" ]; then \ + for file in $$CHANGED_FILES; do \ + sed -i "" -e 's|${VITESS_DIR}||g' $$file; \ + done; \ + else \ + echo "No changed files found."; \ + fi COMMIT_HASH=$(shell cd $(VITESS_DIR) && git rev-parse --short HEAD); \ git add -u content && \ if ! git diff --cached --quiet HEAD --; then \