Skip to content

0.2.0
Compare
Choose a tag to compare
@svengreb svengreb released this 07 Dec 19:48
· 49 commits to main since this release
v0.2.0
This tag was signed with the committer’s verified signature.
svengreb Sven Greb
GPG key ID: 12637B9743D0263D
Learn about vigilant mode.
5c82965

Release Date: 2020-12-07 Project Board Milestone

⇅ Show all commits

This release version comes with a large API breaking change to introduce the new "task" + "runner" based API that uses a “normalized“ naming scheme.

Features

“Task“ API: Simplified usage and “normalized“ naming scheme — #49 ⇄ #51 (⊶ f51a4bf)

↠ With #14 the “abstract“ wand API was introduced with a naming scheme is inspired by the fantasy novel “Harry Potter“ that was used to to define interfaces.
The main motivation was to create a matching naming to the overall “magic“ topic and the actual target project Mage, but in retrospect this is way too abstract and confusing.

The goal of this change was to…

  • rewrite the API to make it way easier to use.
  • use a “normal“ naming scheme.
  • improve all documentations to be more user-scoped and provide guides and examples.

New API Concept

The basic mindset of the API will remain partially the same, but it will be designed around the concept of tasks and the ways to run them.

Command Runner

🅸 task.Runner is a new base interface that runs a command with parameters in a specific environment. It can be compared to the previous 🅸 cast.Caster interface, but provides a cleaner method set accepting the new 🅸 task.Task interface.

  • 🅼 Handles() task.Kind — returns the supported task kind.
  • 🅼 Run(task.Task) error — runs a command.
  • 🅼 Validate() error — validates the runner.

The new 🅸 task.RunnerExec interface is a specialized task.Runner and serves as an abstract representation for a command or action, in most cases a (binary) executable of external commands or Go module main packages, that provides corresponding information like the path to the executable. It can be compared to the previous BinaryCaster interface, but also comes with a cleaner method set and a more appropriate name.

  • 🅼 FilePath() string — returns the path to the (binary) command executable.
Tasks

🅸 task.Task is the new interface that is scoped for Mage “target“ usage. It can be compared to the previous 🅸 spell.Incantation interface, but provides a smaller method set without Formula() []string.

  • 🅼 Kind() task.Kind — returns the task kind.
  • 🅼 Options() task.Options — returns the task options.

The new 🅸 task.Exec interface is a specialized task.Task and serves as an abstract task for an executable command. It can be compared to the previous Binary interface, but also comes with the new BuildParams() []string method that enables a more flexible usage by exposing the parameters for command runner like task.RunnerExec and also allows to compose with other tasks. See the Wikipedia page about the anatomy of a shell CLI for more details about parameters.

  • 🅼 BuildParams() []string — builds the parameters for a command runner where parameters can consist of options, flags and arguments.
  • 🅼 Env() map[string]string — returns the task specific environment.

The new 🅸 task.GoModule interface is a specialized task.Exec for a executable Go module command. It can be compared to the previous spell.GoModule interface and the method set has not changed except a renaming of the GoModuleID() *project.GoModuleID to the more appropriate name ID() *project.GoModuleID. See the official Go module reference documentation for more details about Go modules.

  • 🅼 ID() *project.GoModuleID — returns the identifier of a Go module.

New API Naming Scheme

The following listing shows the new name concept and how the previous API components can be mapped to the changes:

  1. Runner — A component that runs a command with parameters in a specific environment, in most cases a (binary) executable of external commands or Go module main packages. The current API component that can be compared to runners is 🅸 cast.Caster and its specialized interfaces.
  2. Tasks — A component that is scoped for Mage “target“ usage in order to run a action. The current API component that can be compared to tasks is 🅸 spell.Incantation and its specialized interfaces.

API Usage

Even though the API has been changed quite heavily, the basic usage almost did not change.

→ A task.Task can only be run through a task.Runner!

Before a spell.Incantation was passed to a cast.Caster in order to run it, in most cases a (binary) executable of a command that uses the Formula() []string method of spell.Incantation to pass the result as parameters.
The new API works the same: A task.Task is passed to a task.Runner that calls the BuildParams() []string method when the runner is specialized for (binary) executable of commands.

Improved Documentations

Before the documentation was mainly scoped on technical details, but lacked more user-friendly sections about topics like the way how to implement own API components, how to compose the “elder“ reference implementation or usage examples for single or monorepo project layouts.

User Guide

Most of the current sections have been rewritten or removed entirely while new sections now provide more user-friendly guides about how to…

  • use or compose the “elder“ reference implementation.
  • build own tasks and runners using the new API.
  • structure repositories independent of the layout, single or “monorepo“.
Usage Examples

Some examples have been added, that are linked and documented in the user guides described above, to show how to…

  • use or compose the “elder“ reference implementation.
  • build own tasks and runners using the new API.
  • structure repositories independent of the layout, single or “monorepo“.

The full changelog is available in the repository

Copyright © 2019-present Sven Greb

Assets 2
Loading