From 655530c4a3c9f6c1eaa12dd087439965c22faa74 Mon Sep 17 00:00:00 2001 From: per1234 Date: Thu, 5 Aug 2021 18:15:10 -0700 Subject: [PATCH 1/3] Remove obsolete taskfile variables The uses of these was eliminated in the updates to the formatting and documentation infrastructure, but I forgot to remove them from the taskfile at that time. --- Taskfile.yml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index ad563b7ff..f35c36619 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: From d22f6d12bd0fcf76fc182d90be57dda2e86675f3 Mon Sep 17 00:00:00 2001 From: per1234 Date: Thu, 5 Aug 2021 18:28:52 -0700 Subject: [PATCH 2/3] Consolidate convenience "umbrella" tasks There is an established practice of providing the developer with convenience tasks which collect all the domain-specific tasks of a given class. This has a couple of benefits: - Provides an alternative to manually running multiple tasks - Provides a standardized interface to the project, independent from its unique underlying details However, I have come to the conclusion that these benefits lessen as the number of such convenience tasks increases. At the same time, the maintenance burden increases. In the end, I think there are only three distinct classes of tasks that can be consolidated in this manner: - "build" (build the application) - "check" (check for problems with the project) - "fix" (automatically fix problems with the project) --- Taskfile.yml | 73 +++++++++++-------------------------- docs/CONTRIBUTING.md | 85 ++++++-------------------------------------- 2 files changed, 30 insertions(+), 128 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index f35c36619..432eba586 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -35,11 +35,17 @@ tasks: deps: - task: go:build - test: - desc: Run tests - cmds: - - task: go:test - - task: go:test-integration + 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 # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/go-task/Taskfile.yml go:build: @@ -80,43 +86,21 @@ tasks: - poetry run pytest tests check: - desc: Lint and check formatting of all files + desc: Check for problems with the project cmds: - - task: go:check - - task: python:check - - task: docs:check - - task: config:check + - task: ci:validate - task: general:check-formatting - task: general:check-spelling - - task: shell:check-mode - - lint: - desc: Lint all files - cmds: + - task: go:test + - task: go:test-integration - task: go:vet - task: go:lint + - task: markdown:lint + - task: markdown:check-links - task: python:lint - - task: docs:lint - - task: config:lint - - check-formatting: - desc: Check formatting of all files - cmds: - - task: general:check-formatting - - format: - desc: Format all files - cmds: - - task: go:format - - task: python:format - - task: general:format-prettier - - # 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 + - task: shell:check + - task: shell:check-mode + - task: website:check # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-go-task/Taskfile.yml go:vet: @@ -269,13 +253,6 @@ tasks: 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 - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml shell:check: desc: Check for problems with shell scripts @@ -344,16 +321,6 @@ 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 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 From f776e592a34f473f33a0417d3af1782a5f8c68e6 Mon Sep 17 00:00:00 2001 From: per1234 Date: Thu, 5 Aug 2021 19:16:18 -0700 Subject: [PATCH 3/3] Alphabetize tasks I originally set out to establish some logical order to the tasks, based partly on the Arduino CLI taskfile, as that project was used as a model, then on some indecipherable criteria of my own devizing in cases where the model did not provide guidance. In the end, it resulted in a jumble. Alphabetical order is completely objective and it results in a fairly logical order in the end due to the the use of prefixes on the task names according to their domain. The exception is that the convenience "umbrella" tasks have been left at the top (in their own alphabetical order) so that they will have the maximum visibility as the most useful tasks. Even that is not completely inconsistent, since these don't have a namespace prefix, and so might be imagined to have a null global namespace prefix that would be sorted first. --- Taskfile.yml | 304 +++++++++++++++++++++++++-------------------------- 1 file changed, 152 insertions(+), 152 deletions(-) diff --git a/Taskfile.yml b/Taskfile.yml index 432eba586..398cb78d2 100644 --- a/Taskfile.yml +++ b/Taskfile.yml @@ -35,6 +35,23 @@ tasks: deps: - task: go:build + 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 + fix: desc: Make automated corrections to the project's files deps: @@ -47,12 +64,101 @@ tasks: - task: python:format - task: shell:format + # 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/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: + - | + 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/spell-check-task/Taskfile.yml + general:check-spelling: + desc: Check for commonly misspelled words + deps: + - task: poetry:install-deps + cmds: + - poetry run codespell + + # 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: + - poetry run codespell --write-changes + + # 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 . + # 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}} + # 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-go-task/Taskfile.yml + 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:format: + desc: Format Go code + cmds: + - go fmt {{default .DEFAULT_GO_PACKAGES .GO_PACKAGES}} + go:generate: desc: Generate Go code cmds: @@ -63,6 +169,20 @@ tasks: - 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: + desc: Lint Go code + cmds: + - | + if ! which golint &>/dev/null; then + echo "golint not installed or not in PATH. Please install: https://github.com/golang/lint#installation" + exit 1 + fi + - | + golint \ + {{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/test-go-task/Taskfile.yml go:test: desc: Run unit tests @@ -85,67 +205,12 @@ tasks: cmds: - poetry run pytest 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/check-go-task/Taskfile.yml go:vet: desc: Check for errors in Go code cmds: - go vet {{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 - 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:lint: - desc: Lint Go code - cmds: - - | - if ! which golint &>/dev/null; then - echo "golint not installed or not in PATH. Please install: https://github.com/golang/lint#installation" - exit 1 - fi - - | - golint \ - {{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 - cmds: - - go fmt {{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 - cmds: - - npx markdownlint-cli "**/*.md" - - # 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:check-links: desc: Check for broken links @@ -189,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 @@ -201,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 @@ -217,41 +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 + - 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: @@ -281,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 @@ -321,61 +351,31 @@ tasks: )" exit $EXIT_STATUS - # 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