Verify - palantir/godel GitHub Wiki

Summary

The verify task can be used to perform all of the primary operations and checks for a project.

Tutorial start state

  • ${GOPATH}/src/${PROJECT_PATH} exists, is the working directory and is initialized as a Git repository and Go module
  • Project contains godel and godelw
  • Project contains main.go
  • Project contains .gitignore that ignores GoLand files
  • Project contains echo/echo.go, echo/echo_test.go and echo/echoer.go
  • godel/config/dist-plugin.yml is configured to build echgo2
  • Project is tagged as 0.0.1
  • godel/config/dist-plugin.yml is configured to create distributions for echgo
  • Project is tagged as 0.0.2
  • dockerctx directory exists and godel/config/dist-plugin.yml is configured to build Docker images for the product
  • Go files have license headers
  • godel/config/godel.yml is configured to add the go-generate plugin
  • godel/config/generate-plugin.yml is configured to generate string function
  • godel/config/godel.yml is configured to ignore all .+_string.go files
  • integration_test contains integration tests
  • godel/config/test-plugin.yml is configured to specify the "integration" tag
  • docs contains documentation

Verify a project

Over the course of this tutorial, we have configured and used many different tasks -- format to format code, check to run static checks, generate to run "go generate" tasks, license to apply license headers and test to run tests, among others. Remembering to run all of these tasks separately can be a challenge -- in most cases, we simply want to make sure that all of the tasks are run properly and that our code is working.

The ./godelw verify task can be used to do exactly this -- it runs all of the tasks that declare that they provide a "verify" operation. This single task is typically sufficient to ensure that all of the code for a project meets the declarative specifications and that all of the tests in the project pass.

Run ./godelw verify to verify that it runs all the tasks and succeeds:

➜ ./godelw verify
Running format...
Running generate...
Running license...
Running check...
Running compiles...
Finished compiles
Running deadcode...
Finished deadcode
Running errcheck...
Finished errcheck
Running golint...
Finished golint
Running govet...
Finished govet
Running importalias...
Finished importalias
Running ineffassign...
Finished ineffassign
Running outparamcheck...
Finished outparamcheck
Running unconvert...
Finished unconvert
Running varcheck...
Finished varcheck
Running test...
?   	github.com/nmiyake/echgo2                 	[no test files]
ok  	github.com/nmiyake/echgo2/echo            	(cached)
ok  	github.com/nmiyake/echgo2/integration_test	1.603s

Tutorial end state

  • ${GOPATH}/src/${PROJECT_PATH} exists, is the working directory and is initialized as a Git repository and Go module
  • Project contains godel and godelw
  • Project contains main.go
  • Project contains .gitignore that ignores GoLand files
  • Project contains echo/echo.go, echo/echo_test.go and echo/echoer.go
  • godel/config/dist-plugin.yml is configured to build echgo2
  • Project is tagged as 0.0.1
  • godel/config/dist-plugin.yml is configured to create distributions for echgo
  • Project is tagged as 0.0.2
  • dockerctx directory exists and godel/config/dist-plugin.yml is configured to build Docker images for the product
  • Go files have license headers
  • godel/config/godel.yml is configured to add the go-generate plugin
  • godel/config/generate-plugin.yml is configured to generate string function
  • godel/config/godel.yml is configured to ignore all .+_string.go files
  • integration_test contains integration tests
  • godel/config/test-plugin.yml is configured to specify the "integration" tag
  • docs contains documentation

Tutorial next step

Set up CI to run tasks

More

Verify that a project complies with checks without applying changes

The --apply=false flag can be used to run verify in a mode that verifies that the project passes checks without actually modifying it. Specifically, if the verification task reports that it supports a "verify-only" mode, the verify task is run in that mode. The task exits with a non-0 exit code if any of the verifications fail. This task is suitable to run in a CI environment where one wants to verify that a project passes all of its checks without actually modifying it.

Not all tasks support this mode -- if a task does not support this mode, it is run normally and may modify the project. The generate task is such a task -- because go generate can run arbitrary tasks, there is no general way in which verification can be performed besides running the generate tasks and comparing the state of the impacted files before and after the task was run. Running generate with the --apply=false flag will print information about how the state after the run differs from the state before the run for the files specified in the configuration and will cause the verification to fail if differences exist, but the modification will have already been made and will persist after the task.

In general, if a plugin provides a verification task, you should consult its documentation to see if it supports the non-apply behavior.

Skip specific tasks

In some cases, you may want to run verify but skip specific aspects of it -- for example, if the generate task takes a long time to run and you want to run all verification tasks except for generate, you can use the --skip-generate flag to skip the generation step. Run ./godelw verify --help for a full list of the skip flags.