Skip to content

Migration: pkg/errorhandling → go/errorhandling

The error-reporting layer has been extracted out of go-tool-base into the standalone module gitlab.com/phpboyscout/go/errorhandling (v0.1.0). Its only dependency is cockroachdb/errors. It carries no CLI framework at all.

What changed

  • The package gitlab.com/phpboyscout/go-tool-base/pkg/errorhandling no longer exists. It now lives at gitlab.com/phpboyscout/go/errorhandling.
  • Check drops its variadic *cobra.Command parameter:
-Check(err error, prefix string, level string, cmd ...*cobra.Command)
+Check(err error, prefix string, level string)

That parameter existed only to print usage for ErrRunSubCommand, duplicating the SetUsage(func() error) seam that was already on the interface, and no caller in go-tool-base passed it. Removing it is what makes the module framework-free.

  • SlackHelp and TeamsHelp moved to gitlab.com/phpboyscout/go-tool-base/pkg/props. The module defines the HelpConfig interface (the extension point) but ships no implementations: where a team's support channel lives is a framework concern, not an error library's.
  • The mocks moved and are now published by the module at gitlab.com/phpboyscout/go/errorhandling/mocks (MockErrorHandler, MockHelpConfig). mocks/pkg/errorhandling is deleted.
  • Everything else is unchanged: New, ErrorHandler, StandardErrorHandler, Fatal/Error/Warn, SetUsage, the Level* constants, WithExitCode/ExitCode, WithUserHint/WithUserHintf/WrapWithHint, NewAssertionFailure, ErrNotImplemented/NewErrNotImplemented, ErrRunSubCommand, HelpConfig, WithExitFunc, and the Key* log-field constants.

How to migrate

Repoint the import path:

grep -rl 'go-tool-base/pkg/errorhandling' --include='*.go' . \
  | xargs sed -i 's#gitlab.com/phpboyscout/go-tool-base/pkg/errorhandling#gitlab.com/phpboyscout/go/errorhandling#g'
go get gitlab.com/phpboyscout/go/[email protected]
go mod tidy

Then fix the two renames, if you use them:

-errorhandling.SlackHelp{Team: "Platform", Channel: "#help"}
+props.SlackHelp{Team: "Platform", Channel: "#help"}

-import mocks "gitlab.com/phpboyscout/go-tool-base/mocks/pkg/errorhandling"
+import ehmocks "gitlab.com/phpboyscout/go/errorhandling/mocks"

If you passed a command to Check, drop the argument and register the printer once instead: ideally in each command's PreRunE, so the usage shown belongs to the command that actually ran:

-props.ErrorHandler.Check(err, "", errorhandling.LevelError, cmd)
+props.ErrorHandler.SetUsage(cmd.Usage)
+props.ErrorHandler.Check(err, "", errorhandling.LevelError)

Scaffolded projects already do this, gtb generate emits SetUsage(cmd.Usage) in PreRunE, so generated code needs no change beyond the import path.

Notes

  • go-tool-base consumes the module directly. The GTB-specific parts are unchanged and stay in the framework: the Execute wrapper (Cobra silencing, the --help hint on flag-parse errors, signal-aware context, and the single fatal routing point), the SlackHelp/TeamsHelp implementations, and the generator's help wiring. See the Error Handling component.
  • Full documentation: the reporting model, hint guidance, exit-code conventions, and the interrupt-handling patterns, lives at errorhandling.go.phpboyscout.uk; the API reference is on pkg.go.dev.