Add documentation for Task (#130)

* Rename yq task to yq-install * Add documentation for Task * Add descriptions to most tasks I deliberately only described the tasks I expect an end-user of this Taskfile.yml to see when running `task --list`. The others still show up when running `task --list-all`. This in line with the other ...-install tasks.
schubergphilis · Nov 14, 2024 · 4aad9fa · 4aad9fa
1 parent c958f8f
commit 4aad9fa
Show file tree

Hide file tree

Showing 2 changed files with 51 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,13 @@
 # MCVS-golang-action
 
-Mission Critical Vulnerability Scanner (MCVS) Golang Action is a custom
-[GitHub Action](https://github.com/features/actions) that consists of the
-following steps:
+The Mission Critical Vulnerability Scanner (MCVS) Golang Action repository is a
+collection of standardized tools to ensure a certain level of quality of a
+project with Go code.
+
+## Github Action
+
+The [GitHub Action](https://github.com/features/actions) in this repository
+consists of the following steps:
 
 - Install the Golang version that is defined in the project `go.mod`.
 - Verify to be downloaded Golang modules.
@@ -21,6 +26,23 @@ In summary, using this action will ensure that Golang code meets certain
 standards before it will be deployed to production as the assembly line will
 fail if an issue arises.
 
+## Taskfile
+
+Another tool is configuration for [Task](https://taskfile.dev/). This repository
+offers a `Taskfile.yml` which contains standard tasks, like installing and
+running a linter.
+
+This `Taskfile.yml` can then be used by other projects. This has the advantage
+that you do not need to copy and paste Makefile snippets from one project to
+another. As a consequence each project using this `Taskfile.yml` immediately
+benefits from improvements made here (e.g. new tasks or improvements in the
+tasks).
+
+If you are new to Task, you may want to check out the following resources:
+- [Installation instructions](https://taskfile.dev/installation/)
+- Instructions to [configure completions](https://taskfile.dev/installation/#setup-completions)
+- [Integrations](https://taskfile.dev/integrations/) with e.g. Visual Studio Code, Sublime and IntelliJ.
+
 ## Usage
 
 ### Locally
@@ -48,6 +70,15 @@ TASK_X_REMOTE_TASKFILES=1 \
 task remote:test
 ```
 
+Note that the `TASK_X_REMOTE_TASKFILES` variable is required as long as the
+remote Taskfiles are still experimental. (See [issue
+1317](https://github.com/go-task/task/issues/1317) for more information.)
+
+You can use `task --list-all` to get a list of all available tasks.
+Alternatively, if you have [configured
+completions](https://taskfile.dev/installation/#setup-completions) in your
+shell, you can tab to get a list of available tasks.
+
 ### GitHub
 
 Create a `.github/workflows/golang.yml` file with the following content:

diff --git a/Taskfile.yml b/Taskfile.yml
@@ -32,12 +32,13 @@ vars:
 
 tasks:
   build-golang-download-modules:
+    desc: download go modules
     silent: true
     cmds:
       - |
         go mod tidy
-    desc: download go modules
   coverage:
+    desc: check code coverage
     silent: true
     cmds:
       - task: test
@@ -65,6 +66,7 @@ tasks:
           exit 1
         fi
   coverage-visual:
+    desc: show code coverage
     silent: true
     cmds:
       - task: test
@@ -98,6 +100,7 @@ tasks:
           go install github.com/daixiang0/gci@v{{.GCI_VERSION}}
         fi
   gci:
+    desc: check for incorrect import order with gci
     silent: true
     cmds:
       - task: gci-install
@@ -109,6 +112,7 @@ tasks:
           exit 1
         fi
   gci-write:
+    desc: fix incorrect import order with gci
     silent: true
     cmds:
       - task: gci-install
@@ -134,11 +138,13 @@ tasks:
           --timeout 2m30s \
           --verbose
   golangci-lint:
+    desc: run golangci-lint
     silent: true
     cmds:
       - task: golangci-lint-install
       - task: golangci-lint-run
   golangci-lint-run-without-cache:
+    desc: run golangci-lint without cache
     silent: true
     cmds:
       - task: golangci-lint-install
@@ -152,6 +158,7 @@ tasks:
           go install golang.org/x/vuln/cmd/govulncheck@{{.GOVULNCHECK_VERSION}}
         fi
   govulncheck:
+    desc: check for vulnerabilities with govulncheck
     silent: true
     cmds:
       - task: govulncheck-install
@@ -165,19 +172,22 @@ tasks:
           go install github.com/Yamashou/gqlgenc@{{.GQLGENC_VERSION}}
         fi
   lint:
+    desc: run golangci-lint (alias for golangci-lint)
     silent: true
     cmds:
       - task: golangci-lint
   lint-with-gci:
+    desc: run gci and golangci-lint
     silent: true
     deps:
       - task: gci
       - task: golangci-lint
   mock-generate:
+    desc: generate mocks
     silent: true
     cmds:
       - |
-        if ! {{.MOCKERY_BIN}} --version | grep "{{.MOCKERY_VERSION}}"; then       
+        if ! {{.MOCKERY_BIN}} --version | grep "{{.MOCKERY_VERSION}}"; then
           go install github.com/vektra/mockery/{{.MOCKERY_MAJOR_VERSION}}@{{.MOCKERY_VERSION}}
         fi
         echo "{{.MOCK_GENERATE_DIR}} {{.MOCK_GENERATE_INTERFACE_NAME}}"
@@ -187,6 +197,7 @@ tasks:
           --output {{.MOCK_GENERATE_DIR}}/mocks \
           --tags {{.BUILD_TAGS}}
   test:
+    desc: run unit tests
     silent: true
     cmds:
       - |
@@ -200,24 +211,27 @@ tasks:
           ./... \
           {{.TEST_EXTRA_ARGS}}
   test-component:
+    desc: run component tests
     silent: true
     cmds:
       - task: test
         vars:
           TEST_TAGS: component
   test-e2e:
+    desc: run end-to-end tests
     silent: true
     cmds:
       - task: test
         vars:
           TEST_TAGS: e2e
   test-integration:
+    desc: run integration tests
     silent: true
     cmds:
       - task: test
         vars:
           TEST_TAGS: integration
-  yq:
+  yq-install:
     silent: true
     cmds:
       - |