Make github-keeper more end user friendly

[Nicoretti]

An end user whose focus is to fix the issues reported by github-keeper is overloaded with "irrelevant" information. On the other hand essential context information to find and address the issue at hand is missing.

I will illustrate this based on a recent usage error:

Scenario

Check consistency of sqlalchemy-exasol repository.

1. Run github-keeper

 ✘ user@host ~/github-keeper $ go run . configure-repo "sqlalchemy-exasol"

https://github.com/exasol/sqlalchemy-exasol
panic: unsupported type float64

goroutine 1 [running]:
github.com/exasol/github-keeper/cmd.WorkflowDefinitionParser.replaceSpecificParameterInJobName({}, {0xc0000c62a0, 0x20}, {0x822360, 0xc000526f98}, 0x4e328d)
        /home/nic/Projects/github-keeper/cmd/workflowDefinitionParser.go:140 +0x16e
github.com/exasol/github-keeper/cmd.WorkflowDefinitionParser.replaceParametersInJobName({}, {0xc0000c62a0, 0x19}, 0x8e8f6a, {0xc000534ab0, 0x3, 0x3}, 0x0)
        /home/nic/Projects/github-keeper/cmd/workflowDefinitionParser.go:116 +0x1e5
github.com/exasol/github-keeper/cmd.WorkflowDefinitionParser.fillJobNameParametersForMatrixBuild({}, {0xc00009c0b8, 0xc000542f10}, {0xc0000c62a0, 0x6f})
        /home/nic/Projects/github-keeper/cmd/workflowDefinitionParser.go:79 +0x325
github.com/exasol/github-keeper/cmd.getJobNames(0xc0005430b0, {})
        /home/nic/Projects/github-keeper/cmd/workflowDefinitionParser.go:60 +0x125
github.com/exasol/github-keeper/cmd.WorkflowDefinitionParser.ParseWorkflowDefinition({}, {0xc000571000, 0xfbe})
        /home/nic/Projects/github-keeper/cmd/workflowDefinitionParser.go:35 +0xca
github.com/exasol/github-keeper/cmd.BranchProtectionVerifier.getChecksForWorkflowContent({{0x7ffe4bc4322c, 0x0}, 0xc000188000}, {0xc000571000, 0xfbe}, 0xc000542030)
        /home/nic/Projects/github-keeper/cmd/branchProtection.go:230 +0x167
github.com/exasol/github-keeper/cmd.BranchProtectionVerifier.getChecksForWorkflow({{0x7ffe4bc4322c, 0xc000188088}, 0xc000188000}, 0xc000542030)
        /home/nic/Projects/github-keeper/cmd/branchProtection.go:225 +0x85
github.com/exasol/github-keeper/cmd.BranchProtectionVerifier.getRequiredChecks({{0x7ffe4bc4322c, 0xc00018a190}, 0xc000188000}, 0x0)
        /home/nic/Projects/github-keeper/cmd/branchProtection.go:204 +0x1ad
github.com/exasol/github-keeper/cmd.BranchProtectionVerifier.createProtectionRequest({{0x7ffe4bc4322c, 0x98e4f0}, 0xc000188000}, 0x2a)
        /home/nic/Projects/github-keeper/cmd/branchProtection.go:164 +0xa5
github.com/exasol/github-keeper/cmd.BranchProtectionVerifier.CheckIfBranchProtectionIsApplied({{0x7ffe4bc4322c, 0xc000010018}, 0xc000188000}, 0x1e)
        /home/nic/Projects/github-keeper/cmd/branchProtection.go:55 +0x17c
github.com/exasol/github-keeper/cmd.glob..func1(0xca5240, {0xc000063040, 0x1, 0x1})
        /home/nic/Projects/github-keeper/cmd/configureRepo.go:29 +0x15e
github.com/spf13/cobra.(*Command).execute(0xca5240, {0xc000063020, 0x1, 0x1})
        /home/nic/go/pkg/mod/github.com/spf13/cobra@v1.3.0/command.go:860 +0x5f8
github.com/spf13/cobra.(*Command).ExecuteC(0xca59c0)
        /home/nic/go/pkg/mod/github.com/spf13/cobra@v1.3.0/command.go:974 +0x3bc
github.com/spf13/cobra.(*Command).Execute(...)
        /home/nic/go/pkg/mod/github.com/spf13/cobra@v1.3.0/command.go:902
github.com/exasol/github-keeper/cmd.Execute()
        /home/nic/Projects/github-keeper/cmd/root.go:16 +0x25
main.main()
        /home/user/github-keeper/main.go:6 +0x17
exit status 2

2. Try to figure out what went wrong
   • Exit status 2 is not very expressive
   • In order to figure out whats wrong, the user is forced to scroll up quite a bit (depending on the stack trace, it may even is not on the current screen)
   • Error details aren't very helpful from and end user perspective panic: unsupported type float64 -> where was this encountered? file, line, ...

Acceptance criteria

• Stack traces are optional (e.g. add --debug flag)
• Error messages contain more context, e.g. file name, line number, column where the error have been encountered. Create a error file e.g. containing stack trace etc. and report to the user where it can be found ... details see error.txt.
• Add --verbose flag which e.g. then gives status information about current and passed checks e.g.:

  
  checking-workflows:
  - x.y.z ✓ 
  - matrix build names ✓
  other-checks:
  - branch protection settings ✘ 
   details: failed because of ....

[kaklakariada]

@Nicoretti thanks for reporting this. Panics/stack traces like this should not occur in normal operations. We need to fix the root cause of this error. I created https://github.com/exasol/github-keeper/issues/48 to fix bug.

[jakobbraun]

Since this tool is just for us as a team I'm not sure if it's woth investigating further into nicer error messages in case of softweare issues.

[redcatbear]

I agree, that we need to distinguish between programming errors (need to be solved at the root) and runtime errors.

Runtime errors need proper user-centric error messages. Short, precise, expressive and with the necessary context. Programming errors just need to be fixed.