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.