The purpose of this feature is allow the wf2.yaml file to contain a very lightweight, limited & simplistic task list.
There are many times when a project has certain commands or chains of commands that are often run by the developers 'in the know'. The issue is that these 'helper' commands, or 'known fixes' often never make it from the developers head/terminal into any form of documentation.
Even when scripts/commands are documented (for example in a README in the project root) there's nothing stopping those becoming out of date or invalid over time.
The canonical example of where this is a problem comes in the form of Magento 2 performance bundling - where a particular sequence of commands must be ran perfectly in order with exactly the same parameters every time to enable FE/BE to debug problems with bundling locally.
The sequence is something along the lines of
- install FE deps
- build FE assets
- run static-content deploy with correct theme/locale
- run the performance bundling
This could/should still be documented in the project readme as an overview - but we can also do better by saving the commands under 'scripts' in the wf2.yaml file.
Goals (in scope)
- Provide a YAML format for defining commands
- Allow optional names/descriptions for commands for use in documentation/help commands
- Allow composition though sequencing
- Support aliases
- Static analysis of commands to prevent typos (in names, not the actual executable script)
- Output the list of available commands in wf2 help (
wf2 --help
)
None-Goals (out of scope (for now))
- Any kind of helpers/adaptors for interop with composer/npm scripts
- Running tasks in parallel
Proposed format
To prevent adding complexity to the WF2 tool, the feature set will be limited to the following & takes inspiration from the Circle CI format:
scripts:
<name>:
description?: string
steps: (SimpleCommand|ServiceCommand)[]
SimpleCommand: string
ServiceCommand:
service?: string
user?: string
command: string
env?: <name>: <value>[]
Simple Commands
These are commands that are run as-is, meaning they have no special meaning/relationship to WF2
# inside wf2.yaml
scripts:
hello-world:
description: Just an example :)
steps:
- run: echo "hello world"
- run: wf2 m c:f
# you run: wf2 hello-world
WF2 Service Commands
For cases where you want to execute commands directly into a recipe's service (such as mysql) and provide additional things such as cwd
, user
etc.
WF2 will verify that the 'service' you specify actually matches something available in the current recipe before executing.
# inside wf2.yaml
scripts:
hello-world:
description: Just a service command example :)
steps:
- run:
service: mysql
user: root
env:
SOME_ENV: "123456"
command: mysqldump something something
# you run: wf2 hello-world
Combining Simple + Service Commands
Internally, WF2 knows nothing about executing shell scripts/commands, all it does is run things in sequence with a Task abstraction. Because of this, we can easily compose Simple Commands with Service Commands:
# inside wf2.yaml
scripts:
hello-world:
description: Just a service command example :)
steps:
- run: echo "Just about to begin a long process - make a tea"
- run:
service: mysql
user: root
env:
SOME_ENV: "123456"
command: mysqldump something something
- run: echo "All done!"
# you run: wf2 hello-world
Aliases
To make it easier to compose bigger/more complicated tasks, you can use an alias.
# inside wf2.yaml
scripts:
my-alias:
steps:
- run: echo "starting"
- hello-world # <--- alias to the task below
- run: echo "ending!"
hello-world:
description: Just a service command example :)
steps:
- run:
service: mysql
user: root
env:
SOME_ENV: "123456"
command: mysqldump something something
# you run: wf2 hello-world