diff --git a/.github/workflows/checks.yaml b/.github/workflows/checks.yaml index 1ea0cbfabb0..c01eb50f1f5 100644 --- a/.github/workflows/checks.yaml +++ b/.github/workflows/checks.yaml @@ -13,6 +13,9 @@ jobs: - name: check out code uses: actions/checkout@v2 + - name: install dependencies + run: npm install + - name: run markdownlint run: make markdownlint @@ -36,6 +39,9 @@ jobs: - name: check out code uses: actions/checkout@v2 + - name: install dependencies + run: npm install + - name: run markdown-link-check run: make markdown-link-check @@ -45,6 +51,9 @@ jobs: - name: check out code uses: actions/checkout@v2 + - name: install dependencies + run: npm install + - name: run markdown-toc run: make markdown-toc diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 39074b4545e..585bdec8a14 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -42,7 +42,13 @@ one that is needlessly restrictive and complex. ### Consistency Checks The Specification has a number of tools it uses to check things like style, -spelling and link validity. You can run all of these locally via: +spelling and link validity. Before using the tools, run: + +```bash +npm install +``` + +You can perform all checks locally using this command: ```bash make check @@ -92,11 +98,10 @@ wide. There are tools that can do it for you effectively. Please submit proposal to include your editor settings required to enable this behavior so the out of the box settings for this repository will be consistent. -To check for style violations, use +To check for style violations, run: ```bash -make install-markdownlint # install markdownlint if not installed -make markdownlint # run at the root of the repo +make markdownlint ``` To fix style violations, follow the @@ -109,14 +114,15 @@ you can also use the `fixAll` command of the In addition, please make sure to clean up typos before you submit the change. -To check for typos, use +To check for typos, run the following command: ```bash -# Golang is needed for the misspell tool. -make install-misspell make misspell ``` +> **NOTE**: The `misspell` make target will also fetch and build the tool if +> necessary. You'll need [Go](https://go.dev) to build the spellchecker. + To quickly fix typos, use ```bash diff --git a/Makefile b/Makefile index a043a2a0c21..e0d64e4e847 100644 --- a/Makefile +++ b/Makefile @@ -5,9 +5,6 @@ PWD := $(shell pwd) TOOLS_DIR := ./internal/tools MISSPELL_BINARY=bin/misspell MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY) -MARKDOWN_LINK_CHECK=./node_modules/.bin/markdown-link-check -MARKDOWN_LINT=./node_modules/.bin/markdownlint -MARKDOWN_TOC=./node_modules/.bin/markdown-toc # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates # Keep links in semantic_conventions/README.md and .vscode/settings.json in sync! @@ -15,7 +12,7 @@ SEMCONVGEN_VERSION=0.8.0 # TODO: add `yamllint` step to `all` after making sure it works on Mac. .PHONY: all -all: markdownlint markdown-link-check misspell table-check schema-check +all: install-tools markdownlint markdown-link-check misspell table-check schema-check $(MISSPELL): cd $(TOOLS_DIR) && go build -o $(MISSPELL_BINARY) github.com/client9/misspell/cmd/misspell @@ -28,15 +25,13 @@ misspell: $(MISSPELL) misspell-correction: $(MISSPELL) $(MISSPELL) -w $(ALL_DOCS) -$(MARKDOWN_LINK_CHECK): - npm install markdown-link-check - .PHONY: markdown-link-check -markdown-link-check: $(MARKDOWN_LINK_CHECK) - @for f in $(ALL_DOCS); do $(MARKDOWN_LINK_CHECK) --quiet --config .markdown_link_check_config.json $$f; done - -$(MARKDOWN_TOC): - npm install markdown-toc +markdown-link-check: + @if ! npm ls markdown-link-check; then npm install; fi + @for f in $(ALL_DOCS); do \ + npx --no -- markdown-link-check --quiet --config .markdown_link_check_config.json $$f \ + || exit 1; \ + done # This target runs markdown-toc on all files that contain # a comment . @@ -47,22 +42,25 @@ $(MARKDOWN_TOC): # # .PHONY: markdown-toc -markdown-toc: $(MARKDOWN_TOC) +markdown-toc: + @if ! npm ls markdown-toc; then npm install; fi @for f in $(ALL_DOCS); do \ if grep -q '' $$f; then \ echo markdown-toc: processing $$f; \ - $(MARKDOWN_TOC) --no-first-h1 --no-stripHeadingTags -i $$f; \ + npx --no -- markdown-toc --no-first-h1 --no-stripHeadingTags -i $$f || exit 1; \ else \ echo markdown-toc: no TOC markers, skipping $$f; \ fi; \ done -$(MARKDOWN_LINT): - npm install markdownlint-cli@0.31.0 - .PHONY: markdownlint -markdownlint: $(MARKDOWN_LINT) - @for f in $(ALL_DOCS); do echo $$f; $(MARKDOWN_LINT) -c .markdownlint.yaml $$f || exit 1; done +markdownlint: + @if ! npm ls markdownlint; then npm install; fi + @for f in $(ALL_DOCS); do \ + echo $$f; \ + npx --no -p markdownlint-cli markdownlint -c .markdownlint.yaml $$f \ + || exit 1; \ + done .PHONY: install-yamllint install-yamllint: @@ -99,7 +97,7 @@ check: misspell markdownlint markdown-link-check fix: table-generation misspell-correction @echo "All autofixes complete" -# Attempt to install all the tools .PHONY: install-tools -install-tools: $(MISSPELL) $(MARKDOWN_LINT) $(MARKDOWN_LINK_CHECK) $(MARKDOWN_TOC) +install-tools: $(MISSPELL) + npm install @echo "All tools installed" diff --git a/package.json b/package.json new file mode 100644 index 00000000000..94e1ead289a --- /dev/null +++ b/package.json @@ -0,0 +1,7 @@ +{ + "devDependencies": { + "markdown-link-check": "^3.9.3", + "markdown-toc": "^1.2.0", + "markdownlint-cli": "0.31.0" + } +}