diff --git a/Taskfile.yml b/Taskfile.yml index ad563b7ff..398cb78d2 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -28,11 +28,6 @@ vars: -X {{.CONFIGURATION_PACKAGE}}.Commit={{.COMMIT}} -X {{.CONFIGURATION_PACKAGE}}.Timestamp={{.TIMESTAMP}} ' - DOCS_VERSION: dev - DOCS_ALIAS: "" - DOCS_REMOTE: "origin" - - PRETTIER: prettier@2.1.2 tasks: build: @@ -40,100 +35,139 @@ tasks: deps: - task: go:build - test: - desc: Run tests + check: + desc: Check for problems with the project cmds: + - task: ci:validate + - task: general:check-formatting + - task: general:check-spelling - task: go:test - task: go:test-integration + - task: go:vet + - task: go:lint + - task: markdown:lint + - task: markdown:check-links + - task: python:lint + - task: shell:check + - task: shell:check-mode + - task: website:check - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/go-task/Taskfile.yml - go:build: - desc: Build the Go code - cmds: - - go build -v {{.LDFLAGS}} + fix: + desc: Make automated corrections to the project's files + deps: + - task: general:format-prettier + - task: general:correct-spelling + - task: go:generate + - task: go:fix + - task: go:format + - task: markdown:fix + - task: python:format + - task: shell:format - go:generate: - desc: Generate Go code + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml + ci:validate: + desc: Validate GitHub Actions workflows against their JSON schema + vars: + # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-workflow.json + WORKFLOW_SCHEMA_URL: https://json.schemastore.org/github-workflow + WORKFLOW_SCHEMA_PATH: + sh: mktemp -t workflow-schema-XXXXXXXXXX.json + WORKFLOWS_DATA_PATH: "./.github/workflows/*.{yml,yaml}" cmds: - - go install "github.com/go-bindata/go-bindata/...@v3.1.1" - - go-bindata -nocompress -nometadata -o "./internal/rule/schema/schemadata/bindata.go" --pkg schemadata --prefix "./etc/schemas/" "./etc/schemas/" - - go-bindata -nocompress -nometadata -o "./internal/rule/schema/testdata/bindata.go" --pkg testdata --prefix "./internal/rule/schema/testdata/input/" "./internal/rule/schema/testdata/input/" - - go install golang.org/x/tools/cmd/stringer@v0.0.0-20201211192254-72fbef54948b - - go generate ./... - - task: go:format + - | + wget \ + --quiet \ + --output-document="{{.WORKFLOW_SCHEMA_PATH}}" \ + {{.WORKFLOW_SCHEMA_URL}} + - | + npx \ + --package=ajv-cli \ + --package=ajv-formats \ + ajv validate \ + --all-errors \ + --strict=false \ + -c ajv-formats \ + -s "{{.WORKFLOW_SCHEMA_PATH}}" \ + -d "{{.WORKFLOWS_DATA_PATH}}" - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml - go:test: - desc: Run unit tests + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml + docs:generate: + desc: Create all generated documentation content + deps: + - task: go:cli-docs + # Make the formatting consistent with the non-generated Markdown + - task: general:format-prettier + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-general-formatting-task/Taskfile.yml + general:check-formatting: + desc: Check basic formatting style of all files cmds: - | - go test \ - -v \ - -short \ - -run '{{default ".*" .GO_TEST_REGEX}}' \ - {{default "-timeout 10m -coverpkg=./... -covermode=atomic" .GO_TEST_FLAGS}} \ - -coverprofile=coverage_unit.txt \ - {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + if ! which ec &>/dev/null; then + echo "ec not found or not in PATH. Please install: https://github.com/editorconfig-checker/editorconfig-checker#installation" + exit 1 + fi + - ec - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-integration-task/Taskfile.yml - go:test-integration: - desc: Run integration tests + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml + general:check-spelling: + desc: Check for commonly misspelled words deps: - - task: go:build - task: poetry:install-deps cmds: - - poetry run pytest tests + - poetry run codespell - check: - desc: Lint and check formatting of all files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml + general:correct-spelling: + desc: Correct commonly misspelled words where possible + deps: + - task: poetry:install-deps cmds: - - task: go:check - - task: python:check - - task: docs:check - - task: config:check - - task: general:check-formatting - - task: general:check-spelling - - task: shell:check-mode + - poetry run codespell --write-changes - lint: - desc: Lint all files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-prettier-formatting-task/Taskfile.yml + general:format-prettier: + desc: Format all supported files with Prettier cmds: - - task: go:vet - - task: go:lint - - task: python:lint - - task: docs:lint - - task: config:lint + - npx prettier --write . - check-formatting: - desc: Check formatting of all files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/go-task/Taskfile.yml + go:build: + desc: Build the Go code cmds: - - task: general:check-formatting + - go build -v {{.LDFLAGS}} - format: - desc: Format all files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml + go:cli-docs: + desc: Generate command line interface reference documentation + dir: ./docsgen cmds: - - task: go:format - - task: python:format - - task: general:format-prettier + # Command examples use os.Args[0] so the docs generation binary must have the same filename as the project + - go build -o {{.PROJECT_NAME}}{{exeExt}} + # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples + - PATH=. {{.PROJECT_NAME}} ../docs/commands # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml - go:check: - desc: Check for problems with Go code - deps: - - task: go:vet - - task: go:lint + go:fix: + desc: Modernize usages of outdated APIs + cmds: + - go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml - go:vet: - desc: Check for errors in Go code + go:format: + desc: Format Go code cmds: - - go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml - go:fix: - desc: Modernize usages of outdated APIs + go:generate: + desc: Generate Go code cmds: - - go fix {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + - go install "github.com/go-bindata/go-bindata/...@v3.1.1" + - go-bindata -nocompress -nometadata -o "./internal/rule/schema/schemadata/bindata.go" --pkg schemadata --prefix "./etc/schemas/" "./etc/schemas/" + - go-bindata -nocompress -nometadata -o "./internal/rule/schema/testdata/bindata.go" --pkg testdata --prefix "./internal/rule/schema/testdata/input/" "./internal/rule/schema/testdata/input/" + - go install golang.org/x/tools/cmd/stringer@v0.0.0-20201211192254-72fbef54948b + - go generate ./... + - task: go:format # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:lint: @@ -149,23 +183,33 @@ tasks: {{default "-min_confidence 0.8 -set_exit_status" .GO_LINT_FLAGS}} \ {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml - go:format: - desc: Format Go code + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-task/Taskfile.yml + go:test: + desc: Run unit tests cmds: - - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + - | + go test \ + -v \ + -short \ + -run '{{default ".*" .GO_TEST_REGEX}}' \ + {{default "-timeout 10m -coverpkg=./... -covermode=atomic" .GO_TEST_FLAGS}} \ + -coverprofile=coverage_unit.txt \ + {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml - markdown:lint: - desc: Check for problems in Markdown files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/test-go-integration-task/Taskfile.yml + go:test-integration: + desc: Run integration tests + deps: + - task: go:build + - task: poetry:install-deps cmds: - - npx markdownlint-cli "**/*.md" + - poetry run pytest tests - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml - markdown:fix: - desc: Automatically correct linting violations in Markdown files where possible + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml + go:vet: + desc: Check for errors in Go code cmds: - - npx markdownlint-cli --fix "**/*.md" + - go vet {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml markdown:check-links: @@ -210,6 +254,18 @@ tasks: ' fi + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:fix: + desc: Automatically correct linting violations in Markdown files where possible + cmds: + - npx markdownlint-cli --fix "**/*.md" + + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml + markdown:lint: + desc: Check for problems in Markdown files + cmds: + - npx markdownlint-cli "**/*.md" + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry-task/Taskfile.yml poetry:install-deps: desc: Install dependencies managed by Poetry @@ -222,14 +278,6 @@ tasks: cmds: - poetry update - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python-task/Taskfile.yml - python:lint: - desc: Lint Python code - deps: - - task: poetry:install-deps - cmds: - - poetry run flake8 --show-source - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python-task/Taskfile.yml python:format: desc: Format Python files @@ -238,48 +286,13 @@ tasks: cmds: - poetry run black . - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml - docs:generate: - desc: Create all generated documentation content - deps: - - task: go:cli-docs - # Make the formatting consistent with the non-generated Markdown - - task: general:format-prettier - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/deploy-cobra-mkdocs-versioned-poetry/Taskfile.yml - go:cli-docs: - desc: Generate command line interface reference documentation - dir: ./docsgen - cmds: - # Command examples use os.Args[0] so the docs generation binary must have the same filename as the project - - go build -o {{.PROJECT_NAME}}{{exeExt}} - # The binary is invoked like this instead of `./{{.PROJECT_NAME}}` to remove the `./` chars from the examples - - PATH=. {{.PROJECT_NAME}} ../docs/commands - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml - website:check: - desc: Check whether the MkDocs-based website will build - deps: - - task: docs:generate - - task: poetry:install-deps - cmds: - - poetry run mkdocs build --strict - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml - website:serve: - desc: Run website locally + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python-task/Taskfile.yml + python:lint: + desc: Lint Python code deps: - - task: docs:generate - task: poetry:install-deps cmds: - - poetry run mkdocs serve - - docs:check: - desc: Lint and check formatting of documentation files - cmds: - - task: markdown:lint - - task: markdown:fix - - task: markdown:check-links + - poetry run flake8 --show-source # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check: @@ -309,17 +322,6 @@ tasks: \) ) - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml - shell:format: - desc: Format shell script files - cmds: - - | - if ! which shfmt &>/dev/null; then - echo "shfmt not installed or not in PATH. Please install: https://github.com/mvdan/sh#shfmt" - exit 1 - fi - - shfmt -w . - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check-mode: desc: Check for non-executable shell scripts @@ -349,71 +351,31 @@ tasks: )" exit $EXIT_STATUS - config:check: - desc: Lint and check formatting of configuration files - cmds: - - task: config:lint - - config:lint: - desc: Lint configuration files - cmds: - - task: workflow:validate - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml - ci:validate: - desc: Validate GitHub Actions workflows against their JSON schema - vars: - # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-workflow.json - WORKFLOW_SCHEMA_URL: https://json.schemastore.org/github-workflow - WORKFLOW_SCHEMA_PATH: - sh: mktemp -t workflow-schema-XXXXXXXXXX.json - WORKFLOWS_DATA_PATH: "./.github/workflows/*.{yml,yaml}" - cmds: - - | - wget \ - --quiet \ - --output-document="{{.WORKFLOW_SCHEMA_PATH}}" \ - {{.WORKFLOW_SCHEMA_URL}} - - | - npx \ - --package=ajv-cli \ - --package=ajv-formats \ - ajv validate \ - --all-errors \ - --strict=false \ - -c ajv-formats \ - -s "{{.WORKFLOW_SCHEMA_PATH}}" \ - -d "{{.WORKFLOWS_DATA_PATH}}" - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-general-formatting-task/Taskfile.yml - general:check-formatting: - desc: Check basic formatting style of all files + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml + shell:format: + desc: Format shell script files cmds: - | - if ! which ec &>/dev/null; then - echo "ec not found or not in PATH. Please install: https://github.com/editorconfig-checker/editorconfig-checker#installation" + if ! which shfmt &>/dev/null; then + echo "shfmt not installed or not in PATH. Please install: https://github.com/mvdan/sh#shfmt" exit 1 fi - - ec - - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-prettier-formatting-task/Taskfile.yml - general:format-prettier: - desc: Format all supported files with Prettier - cmds: - - npx prettier --write . + - shfmt -w . - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml - general:check-spelling: - desc: Check for commonly misspelled words + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml + website:check: + desc: Check whether the MkDocs-based website will build deps: + - task: docs:generate - task: poetry:install-deps cmds: - - poetry run codespell + - poetry run mkdocs build --strict - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml - general:correct-spelling: - desc: Correct commonly misspelled words where possible + # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-mkdocs-task/Taskfile.yml + website:serve: + desc: Run website locally deps: + - task: docs:generate - task: poetry:install-deps cmds: - - poetry run codespell --write-changes + - poetry run mkdocs serve diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 1935cb14f..d54ec54dc 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -95,24 +95,18 @@ task build The project uses Go modules, so dependencies will be downloaded automatically. At the end of the build, you should find the `arduino-lint` executable in the same folder. -### Running the tests + -There are several checks and test suites in place to ensure the code works as expected and is written in a way that's -consistent across the whole codebase. To avoid pushing changes that will cause the CI system to fail, you can run most -of the tests locally. +### Running the checks -To ensure code style is consistent, run: +There are several checks and test suites in place to ensure the code works as expected and is written in a way that's +consistent across the whole codebase. To avoid pushing changes that will cause the CI system to fail, you can run the +checks locally by running this command: ``` task check ``` -To run all tests: - -``` -task test -``` - #### Go unit tests To run only the Go unit tests, run: @@ -173,49 +167,17 @@ pytest test_lib.py pytest test_lib.py::test_list ``` -#### Linting and formatting - -When editing any Python file in the project, remember to run linting checks with: - -``` -task python:check -``` + -This will run [`flake8`](https://flake8.pycqa.org/) automatically and return any error in the code formatting. +### Automated corrections -In case of linting errors you should be able to solve most of them by automatically formatting with: +Tools are provided to automatically bring the project into compliance with some required checks. Run them all with this +command: -```shell -task python:format ``` - -#### Configuration files formatting - -We use [Prettier](https://prettier.io/) to automatically format all YAML files in the project. Keeping and enforcing a -formatting standard helps everyone make small PRs and avoids the introduction of formatting changes made by unconfigured -editors. - -There are several ways to run Prettier. If you're using Visual Studio Code you can easily use the -[`prettier-vscode` extension](https://github.com/prettier/prettier-vscode) to automatically format as you write. - -Otherwise you can use the following tasks. To do so you'll need to install `npm` if not already installed. Check the -[official documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to learn how to install -`npm` for your platform. - -To check if the files are correctly formatted run: - -```shell -task config:check +task fix ``` -If the output tells you that some files are not formatted correctly run: - -```shell -task config:format -``` - -Checks are automatically run on every pull request to verify that configuration files are correctly formatted. - ### Working on documentation Documentation is provided to final users in form of static HTML content generated from a tool called @@ -238,33 +200,6 @@ task website:serve The documentation will build. If you don't see any error, open `http://127.0.0.1:8000` in your browser to local the local copy of the documentation. -#### Documentation formatting - -We use [Prettier](https://prettier.io/) to automatically format all Markdown files in the project. Keeping and enforcing -a formatting standard helps everyone make small PRs and avoids the introduction of formatting changes made by -misconfigured editors. - -There are several ways to run Prettier. If you're using Visual Studio Code you can easily use the -[`prettier-vscode` extension](https://github.com/prettier/prettier-vscode) to automatically format as you write. - -Otherwise you can use the following tasks. To do so you'll need to install `npm` if not already installed. Check the -[official documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) to learn how to install -`npm` for your platform. - -To check if the files are correctly formatted run: - -```shell -task website:check -``` - -If the output tells you that some files are not formatted correctly run: - -```shell -task docs:format -``` - -Checks are automatically run on every pull request to verify that documentation is correctly formatted. - #### Documentation publishing The Arduino Lint git repository has a special branch called `gh-pages` that contains the generated HTML code for the