This patch release improves documentation.

This major release improves the command-line interface and changes the A.Context behavior to match testing.T.Context.

Migration Guide from v2 to v3

Module Path Change

Update your import statements and go.mod.

// Before (v2)
import "github.com/goyek/goyek/v2"

// After (v3)
import "github.com/goyek/goyek/v3"

Command Line Syntax Change

The recommended command line syntax changed from [flags] [--] [tasks] to
[tasks] [flags] [--] [args].

// Before (v2)
func main() {
    flag.Parse()
    goyek.Main(flag.Args())
}

// After (v3)
func main() {
    tasks, rest := goyek.SplitTasks(os.Args[1:])
    flag.CommandLine.Parse(rest)
    goyek.Main(tasks)
}

Context Behavior Change

A.Context is now canceled just before cleanup functions are called. If your cleanup functions depend on the context being active, they will continue to work. If your code depended on the context remaining active after cleanup, it will need adjustment.

// Before (v2): Context stayed active during cleanup.
goyek.Define(goyek.Task{
    Name: "example",
    Action: func(a *goyek.A) {
        a.Cleanup(func() {
            // Context was still active here.
        })
    },
})

// After (v3): Context cancels before cleanup (matches testing.T behavior).
goyek.Define(goyek.Task{
    Name: "example",
    Action: func(a *goyek.A) {
        a.Cleanup(func() {
            // Context is canceled here, allowing proper shutdown
            // of resources that listen to context.Done().
        })
    },
})

Added

• Add SplitTasks function to split command line arguments into tasks and rest. This allows tasks to come before flags and usage of positional arguments.

Changed

• BREAKING: Change module path to github.com/goyek/goyek/v3.
• BREAKING: Change A.Context behavior to be canceled just before cleanup functions are called, matching testing.T.Context behavior. The context still cancels when the original context is canceled (e.g. flow interruption). This ensures cleanup functions can wait for resources that shut down on context.Context.Done before the task action completes.

This release adds A.WithContext inspired by http.Request.WithContext and A.Chdir following testing.T.Chdir.

Added

• Add A.WithContext that creates a derived A with a changed context. Thanks to it A can be reused to pass cancelation and values via context to the helper functions.
• Add A.Chdir that changes the current working directory and during action cleanup restores it to its original value.

This release adds flow execution middlewares.

Added

• Add Flow.UseExecutor to support flow execution interception using middlewares.
• Add middleware.ReportFlow flow execution middleware which reports the flow execution status.

Change

• Extract the flow result reporting from Flow.Main to middleware.ReportFlow. Add the middleware using Flow.UseExecutor to achieve a backward compatible behavior.

Removed

• Drop support for Go 1.11 and 1.12.

This release adds parallel task execution support.

Added

• Add Task.Parallel to allow running tasks in parallel.
• Add middleware.BufferParallel that helps in not getting mixed output from parallel tasks execution.
• Add Input.Parallel to allow middlewares to have special handling for parallel tasks.

This release contains many breaking changes that are necessary to improve usability, extensibility, and customization. You can also find new supplemental features in goyek/x.

Added

• Add DefaultFlow which is the default flow.
• Add the top-level functions such as Define, Main, and so on which are wrappers for the methods of Flow called for DefaultFlow.
• Flow.Main now exits on receiving the second SIGINT.
• Add Flow.Print for printing the flow usage.
• Flow.Main and Flow.Execute allow passing execution options.
• Add NoDeps option to skip processing of all dependencies.
• Add Skip option to skip processing of given tasks.
• Add Flow.Usage, Flow.SetUsage for getting and setting the function that is called when an error occurs while parsing the flow.
• Add NOOP status report for tasks that were intentionally not run to differentiate from being skipped during execution.
• Add Flow.Use method o support task run interception using middlewares.
• Add middleware package with ReportStatus, SilentNonFailed, DryRun, ReportLongRun middlewares.
• TF.Error, TF.Errorf, TF.Fail may be called simultaneously from multiple goroutines.
• Add NewRunner which can be useful for testing and debugging task actions and middlewares.
• Add Flow.Undefine to unregister a task.
• Add DefinedTask.SetName, DefinedTask.SetUsage, DefinedTask.Action, DefinedTask.SetAction, DefinedTask.SetAction, DefinedTask.SetDeps to enable modifying the task after the initial definition.
• Add Flow.SetLogger for setting a custom log decorator that is used by A logging methods. If Logger implements Error, Errorf, Fatal, Fatalf, Skip, Skipf, they will be used by the A equivalent methods.
• Add Flow.Logger for getting the log decorator (CodeLineLogger by default).
• Add CodeLineLogger which is the default for Flow.Logger.
• Add FmtLogger which is the default when using NewRunner.
• Add A.Helper and CodeLineLogger.Helper methods that work like the equivalent method in the testing package.
• Add A.Cleanup method that registers an action's cleanup function.
• Add A.Setenv method that sets the environment variable and reverts the previous value during cleanup.
• Add A.TempDir method that creates a temporary directory and removes it during cleanup.

Changed

• Rename TF type to A as this is the Action parameter. This is the most impactful breaking change. This follows the convention used in the testing package to name the parameter type as the first letter of the "function type".
• Task status reporting is disabled by default. It can be enabled by calling Flow.Use(middleware.ReportStatus). It reports NOOP for a task without an action.
• Usually, the task does not call panic directly. panic failure message no longer contains a prefix with file and line information. The stack trace is printed instead. The behavior is based on testing package.
• RegisteredTask.Deps returns []string (dependency names) for easier introspection.
• Rename Flow.Register to Flow.Define.
• Change Flow.RegisteredTask to Flow.DefinedTask.
• DefinedTask.Deps returns Deps to facilitate reusing defined task's dependencies when creating a new one or redefining an existing one.
• Change the Flow.DefaultTask field to Flow.SetDefault and Flow.Default methods.
• Change Flow.Output field to Flow.SetOutput setter and Flow.Output getter.
• Change Flow.Run to Flow.Execute to reduce possible confusion with Runner.
• Flow.Execute returns an error instead of returning the exit code and does not print to output. It also has different arguments.
• Flow.Execute accepts []string instead of ...string to make the API forward compatible.

Removed

• Remove parameters API and out-of-the-box flags (-v, -wd).
• Remove A.Cmd. Use github.com/goyek/goyek/x/cmd or your helper instead.

Fixed

• Fix panic handling so that panic(nil) and runtime.Goexit() now cause task failure.

Removed

• Remove A.Cmd. Use github.com/goyek/goyek/x/cmd or your own helper instead.

Changed

• Flow.Main no longer changes the working directory (undocumented behavior).

This release adds helpers methods for type A that are commonly used in the testing package.

Added

• Add A.Cleanup method that registers an action's cleanup function.
• Add A.Setenv method that sets the environment variable and reverts the previous value during cleanup.
• Add A.TempDir method that creates a temporary directory and removes it during cleanup.

This release introduces a breaking change as it renames the heavily used TF type to A. This follows the convention used in testing package to name the parameter type as the first letter of the "function type".

Added

• Add Status.String method for printing Status.

Changed

• Rename TF type to A as this is the Action parameter.