Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit 1032be0

Browse files
author
test
committedApr 25, 2024·
Implement pup workflows and add docs
1 parent 9094b4a commit 1032be0

25 files changed

+379
-11
lines changed
 

‎.puprc-defaults

+1
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"build": [],
33
"build_dev": [],
4+
"workflows": {},
45
"checks": {
56
"tbd": {
67
"fail_method": "error",

‎README.md

+6
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,13 @@ This is a CLI utility built by [StellarWP](https://stellarwp.com) for running pr
2020
* [`pup check:tbd`](/docs/commands.md#pup-checktbd)
2121
* [`pup check:version-conflict`](/docs/commands.md#pup-checkversion-conflict)
2222
* [`pup clean`](/docs/commands.md#pup-clean)
23+
* [`pup do`](/docs/commands.md#pup-do)
2324
* [`pup get-version`](/docs/commands.md#pup-get-version)
2425
* [`pup help`](/docs/commands.md#pup-help)
2526
* [`pup i18n`](/docs/commands.md#pup-i18n)
2627
* [`pup info`](/docs/commands.md#pup-info)
2728
* [`pup package`](/docs/commands.md#pup-package)
29+
* [`pup workflow`](/docs/commands.md#pup-workflow)
2830
* [`pup zip`](/docs/commands.md#pup-zip)
2931
* [`pup zip-name`](/docs/commands.md#pup-zip-name)
3032
* [Command flow for `pup zip`](/docs/flow.md)
@@ -35,5 +37,9 @@ This is a CLI utility built by [StellarWP](https://stellarwp.com) for running pr
3537
* [Creating custom checks](#creating-custom-checks)
3638
* [Simple checks](#simple-checks)
3739
* [Class-based checks](#class-based-checks)
40+
* [Workflows](/docs/workflows.md)
41+
* [Defining workflows](/docs/workflows.md#defining-workflows)
42+
* [Calling workflows](/docs/workflows.md#calling-workflows)
43+
* [Pseudo-workflows](/docs/workflows.md#pseudo-workflows)
3844
* Examples
3945
* [GitHub Workflow: Zipping](/examples/workflows/zip.yml) - Breaks up the `pup zip` command into multiple steps so debugging is easy.

‎docs/commands.md

+26
Original file line numberDiff line numberDiff line change
@@ -274,6 +274,32 @@ composer -- pup package <version>
274274
## `pup workflow`
275275
Run a command workflow.
276276

277+
An example workflow might look like this:
278+
279+
```json
280+
{
281+
"workflow": {
282+
"my-workflow": [
283+
"npm ci",
284+
"npm run build",
285+
"@composer run some-script"
286+
]
287+
}
288+
}
289+
```
290+
291+
Executing this workflow would work like this:
292+
293+
```bash
294+
pup workflow my-workflow
295+
# OR
296+
pup do my-workflow
297+
# OR
298+
composer -- pup workflow my-workflow
299+
# OR
300+
composer -- pup do my-workflow
301+
```
302+
277303
### Usage
278304
```bash
279305
pup workflow <workflow>

‎docs/configuration.md

+11-10
Original file line numberDiff line numberDiff line change
@@ -5,15 +5,16 @@ root of the project. This file is a JSON file that contains the configuration op
55

66
## Top-level properties
77

8-
| Property | Type | Description |
9-
|-------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------|
10-
| `build` | `array` | An array of CLI commands to execute for the build process of your project. |
11-
| `build_dev` | `array` | An array of CLI commands to execute for the `--dev` build process of your project. If empty, it defaults to the value of `build` |
12-
| `checks` | `object` | An object of check configurations indexed by the check's slug. See the [docs for checks](/docs/checks.md) for more info. |
13-
| `paths` | `object` | An object containing paths used by `pup`. [See below](#paths). |
14-
| `repo` | `string`/`null` | The git repo used to clone the project. If not provided, at github URL is generated based on the `name` property of `composer.json` |
15-
| `zip_use_default_ignore` | `boolean` | Whether or not additionally ignore files based on the [`.distignore-defaults`](/.distignore-defaults) file. Defaults to `true`. |
16-
| `zip_name` | `string` | The name of the zip file to be generated. Defaults to the name of the project as set in `composer.json`. |
8+
| Property | Type | Description |
9+
|-------------|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
10+
| `build` | `array` | An array of CLI commands to execute for the build process of your project. |
11+
| `build_dev` | `array` | An array of CLI commands to execute for the `--dev` build process of your project. If empty, it defaults to the value of `build` |
12+
| `checks` | `object` | An object of check configurations indexed by the check's slug. See the [docs for checks](/docs/checks.md) for more info. |
13+
| `paths` | `object` | An object containing paths used by `pup`. [See below](#paths). |
14+
| `repo` | `string`/`null` | The git repo used to clone the project in the format of `<org>/<repo>`. If not provided, at github URL is generated based on the `name` property of `composer.json` |
15+
| `workflows` | `object` | An object of workflow configurations. The index is the workflow slug and the values are arrays of strings that hold commands. See the [docs for workflows](/docs/workflows.md) for more info. |
16+
| `zip_use_default_ignore` | `boolean` | Whether or not additionally ignore files based on the [`.distignore-defaults`](/.distignore-defaults) file. Defaults to `true`. |
17+
| `zip_name` | `string` | The name of the zip file to be generated. Defaults to the name of the project as set in `composer.json`. |
1718

1819
## Paths
1920

@@ -135,4 +136,4 @@ This is what you should add as a `paths.versions` entry:
135136
]
136137
}
137138
}
138-
```
139+
```

‎docs/workflows.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Workflows
2+
3+
Workflows are a way to declare a series of commands that you want to run in a specific order. This allows you to specify
4+
workflows that differ from the `build` and `build_dev` commands.
5+
6+
* [Defining workflows](#defining-workflows)
7+
* [Calling workflows](#calling-workflows)
8+
* [Pseudo-workflows](#pseudo-workflows)
9+
10+
## Defining workflows
11+
12+
Workflows are defined in the `workflows` property of your `.puprc` file.
13+
14+
```json
15+
{
16+
"workflows": {
17+
"my-workflow": [
18+
"npm ci",
19+
"npm run build",
20+
"@composer run some-script"
21+
],
22+
"my-other-workflow": [
23+
"@composer run some-other-script",
24+
"@composer run make-pot"
25+
]
26+
}
27+
}
28+
```
29+
30+
## Calling workflows
31+
32+
You can call a workflow by running the `workflow` command (or its alias `do`) with the name of the workflow as an argument.
33+
34+
```bash
35+
pup workflow my-workflow
36+
# OR
37+
pup do my-workflow
38+
```
39+
40+
## Pseudo-workflows
41+
42+
The `build` and `build_dev` properties within your `.puprc` file are also callable via the `workflow` command.
43+
44+
```bash
45+
pup workflow build
46+
```

‎src/Commands/Workflow.php

+1-1
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ protected function execute( InputInterface $input, OutputInterface $output ) {
5757

5858
$workflow = $collection->get( $workflow_slug );
5959
if ( ! $workflow ) {
60-
$io->writeln( "<error>The workflow '{$workflow_slug}' does not exist.</error>" );
60+
$io->writeln( "<error>The workflow '{$workflow_slug}' does not exist.</error>" );
6161
return 1;
6262
}
6363

‎src/Workflow/Collection.php

+3
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,9 @@ public function offsetExists( $offset ): bool {
7171
*/
7272
#[\ReturnTypeWillChange]
7373
public function offsetGet( $offset ) {
74+
if ( ! isset( $this->workflows[ $offset ] ) ) {
75+
return null;
76+
}
7477
return $this->workflows[ $offset ];
7578
}
7679

‎tests/cli/Commands/HelpCest.php

+2
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,12 @@ protected function topicProvider(): array {
5454
[ 'topic' => 'check' ],
5555
[ 'topic' => 'check:tbd' ],
5656
[ 'topic' => 'check:version-conflict' ],
57+
[ 'topic' => 'do' ],
5758
[ 'topic' => 'help' ],
5859
[ 'topic' => 'i18n' ],
5960
[ 'topic' => 'get-version' ],
6061
[ 'topic' => 'package' ],
62+
[ 'topic' => 'workflow' ],
6163
[ 'topic' => 'zip' ],
6264
[ 'topic' => 'zip-name' ],
6365
];

‎tests/cli/Commands/WorkflowCest.php

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?php
2+
3+
namespace StellarWP\Pup\Tests\Cli\Commands;
4+
5+
use StellarWP\Pup\Tests\Cli\AbstractBase;
6+
use StellarWP\Pup\Tests\CliTester;
7+
8+
class WorkflowCest extends AbstractBase {
9+
public function _before( CliTester $I ) {
10+
parent::_before( $I );
11+
}
12+
13+
/**
14+
* @test
15+
*/
16+
public function it_should_run_workflow( CliTester $I ) {
17+
$puprc = $this->get_puprc();
18+
$puprc['workflows'] = [];
19+
$puprc['workflows']['bork'] = [];
20+
$puprc['workflows']['bork'][] = 'echo "fake project, yo"';
21+
$this->write_puprc( $puprc );
22+
23+
chdir( $this->tests_root . '/_data/fake-project' );
24+
25+
$I->runShellCommand( "php {$this->pup} workflow bork" );
26+
$I->seeResultCodeIs( 0 );
27+
$I->seeInShellOutput( 'fake project, yo' );
28+
$I->seeInShellOutput( 'Workflow complete.' );
29+
30+
$output = $I->grabShellOutput();
31+
$this->assertMatchesStringSnapshot( $output );
32+
}
33+
34+
/**
35+
* @test
36+
*/
37+
public function it_should_run_do( CliTester $I ) {
38+
$puprc = $this->get_puprc();
39+
$puprc['workflows'] = [];
40+
$puprc['workflows']['bork'] = [];
41+
$puprc['workflows']['bork'][] = 'echo "fake project, yo"';
42+
$this->write_puprc( $puprc );
43+
44+
chdir( $this->tests_root . '/_data/fake-project' );
45+
46+
$I->runShellCommand( "php {$this->pup} do bork" );
47+
$I->seeResultCodeIs( 0 );
48+
$I->seeInShellOutput( 'fake project, yo' );
49+
$I->seeInShellOutput( 'Workflow complete.' );
50+
51+
$output = $I->grabShellOutput();
52+
$this->assertMatchesStringSnapshot( $output );
53+
}
54+
55+
/**
56+
* @test
57+
*/
58+
public function it_should_run_build_as_workflow( CliTester $I ) {
59+
$puprc = $this->get_puprc();
60+
$puprc['build'][] = 'echo "fake project, yo"';
61+
$this->write_puprc( $puprc );
62+
63+
chdir( $this->tests_root . '/_data/fake-project' );
64+
65+
$I->runShellCommand( "php {$this->pup} do build" );
66+
$I->seeResultCodeIs( 0 );
67+
$I->seeInShellOutput( 'fake project, yo' );
68+
$I->seeInShellOutput( 'Workflow complete.' );
69+
70+
$output = $I->grabShellOutput();
71+
$this->assertMatchesStringSnapshot( $output );
72+
}
73+
74+
/**
75+
* @test
76+
*/
77+
public function it_should_run_build_dev_as_workflow( CliTester $I ) {
78+
$puprc = $this->get_puprc();
79+
$puprc['build_dev'][] = 'echo "fake project, yo"';
80+
$this->write_puprc( $puprc );
81+
82+
chdir( $this->tests_root . '/_data/fake-project' );
83+
84+
$I->runShellCommand( "php {$this->pup} do build_dev" );
85+
$I->seeResultCodeIs( 0 );
86+
$I->seeInShellOutput( 'fake project, yo' );
87+
$I->seeInShellOutput( 'Workflow complete.' );
88+
89+
$output = $I->grabShellOutput();
90+
$this->assertMatchesStringSnapshot( $output );
91+
}
92+
93+
/**
94+
* @test
95+
*/
96+
public function it_should_run_an_empty_workflow( CliTester $I ) {
97+
$puprc = $this->get_puprc();
98+
$puprc['workflows'] = [];
99+
$puprc['workflows']['bork'] = [];
100+
$this->write_puprc( $puprc );
101+
102+
chdir( $this->tests_root . '/_data/fake-project' );
103+
104+
$I->runShellCommand( "php {$this->pup} do bork" );
105+
$I->seeResultCodeIs( 0 );
106+
107+
$output = $I->grabShellOutput();
108+
$this->assertMatchesStringSnapshot( $output );
109+
}
110+
111+
/**
112+
* @test
113+
*/
114+
public function it_should_fail_non_existent_workflow( CliTester $I ) {
115+
$puprc = $this->get_puprc();
116+
$puprc['workflows'] = [];
117+
$puprc['workflows']['bork'] = [];
118+
$puprc['workflows']['bork'][] = 'echo "fake project, yo"';
119+
$this->write_puprc( $puprc );
120+
121+
chdir( $this->tests_root . '/_data/fake-project' );
122+
123+
$I->runShellCommand( "php {$this->pup} workflow whee", false );
124+
$I->seeResultCodeIs( 1 );
125+
$I->seeInShellOutput( '\'whee\' does not exist.' );
126+
127+
$output = $I->grabShellOutput();
128+
$this->assertMatchesStringSnapshot( $output );
129+
}
130+
}

‎tests/cli/Commands/__snapshots__/HelpCest__it_should_default_to_help__0.snapshot.txt

+2
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,13 @@ Run pup help <topic> for more information on a specific command.
1616
check:version-conflict Verifies that all of your version numbers match.
1717
check Runs all registered check commands.
1818
clean This command cleans up any directories that pup creates.
19+
do Alias for pup workflow. See pup help workflow for more information.
1920
get-version Gets your project's version number.
2021
help Shows the help menu.
2122
i18n Pulls in translations from a GlotPress instance.
2223
info Gets pup details for the current project.
2324
package Packages your project into a zip file with the passed in version number.
25+
workflow Run a command workflow.
2426
zip-name Gets your project's zip name (sans the .zip extension).
2527
zip Runs the full pup set of commands to create a zip file.
2628
------------------------ -------------------------------------------------------------------------------

‎tests/cli/Commands/__snapshots__/HelpCest__it_should_run_help__0.snapshot.txt

+2
Original file line numberDiff line numberDiff line change
@@ -16,11 +16,13 @@ Run pup help <topic> for more information on a specific command.
1616
check:version-conflict Verifies that all of your version numbers match.
1717
check Runs all registered check commands.
1818
clean This command cleans up any directories that pup creates.
19+
do Alias for pup workflow. See pup help workflow for more information.
1920
get-version Gets your project's version number.
2021
help Shows the help menu.
2122
i18n Pulls in translations from a GlotPress instance.
2223
info Gets pup details for the current project.
2324
package Packages your project into a zip file with the passed in version number.
25+
workflow Run a command workflow.
2426
zip-name Gets your project's zip name (sans the .zip extension).
2527
zip Runs the full pup set of commands to create a zip file.
2628
------------------------ -------------------------------------------------------------------------------

‎tests/cli/Commands/__snapshots__/HelpCest__it_should_show_topic_docs__10.snapshot.txt

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
2+
Help: pup build
3+
===============
4+
5+
Runs the build commands from the .puprc file.
6+
7+
8+
If you want your dev builds to build differently, you can add a build_dev property to your .puprc file.
9+
10+
> Usage:
11+
--------
12+
13+
..................................................
14+
pup build [--dev]
15+
# or
16+
composer -- pup build [--dev]
17+
..................................................
18+
19+
> Arguments:
20+
------------
21+
22+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
23+
Argument Description
24+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
25+
--dev Optional. Whether or not this is a dev build. Using this option will run the build_dev commands from your .puprc file if they exist, otherwise it will run build commands.
26+
--root Optional. Run the command from a different directory from the current.
27+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
28+
29+
30+
> Specifying build commands:
31+
----------------------------
32+
33+
You can specify build commands within your .puprc file by adding to either the build or build_dev properties. These
34+
commands will be run in the order they are specified. By default, if any command fails, the build will fail. You can,
35+
however, prepend your commands with @ and that will tell pup to ignore failures for that step. Here's an example:
36+
37+
..................................................
38+
{
39+
"build": [
40+
"npm ci",
41+
"npm run build",
42+
"@composer run some-script"
43+
]
44+
}
45+
..................................................
46+
47+
In the above example, npm ci and npm run build will need to complete successfully for the build to succeed, but the
48+
composer run some-script is prepended by @ so if it fails, the build will continue forward.

‎tests/cli/Commands/__snapshots__/HelpCest__it_should_show_topic_docs__9.snapshot.txt

+48
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
2+
Help: pup build
3+
===============
4+
5+
Runs the build commands from the .puprc file.
6+
7+
8+
If you want your dev builds to build differently, you can add a build_dev property to your .puprc file.
9+
10+
> Usage:
11+
--------
12+
13+
..................................................
14+
pup build [--dev]
15+
# or
16+
composer -- pup build [--dev]
17+
..................................................
18+
19+
> Arguments:
20+
------------
21+
22+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
23+
Argument Description
24+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
25+
--dev Optional. Whether or not this is a dev build. Using this option will run the build_dev commands from your .puprc file if they exist, otherwise it will run build commands.
26+
--root Optional. Run the command from a different directory from the current.
27+
---------- ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- --
28+
29+
30+
> Specifying build commands:
31+
----------------------------
32+
33+
You can specify build commands within your .puprc file by adding to either the build or build_dev properties. These
34+
commands will be run in the order they are specified. By default, if any command fails, the build will fail. You can,
35+
however, prepend your commands with @ and that will tell pup to ignore failures for that step. Here's an example:
36+
37+
..................................................
38+
{
39+
"build": [
40+
"npm ci",
41+
"npm run build",
42+
"@composer run some-script"
43+
]
44+
}
45+
..................................................
46+
47+
In the above example, npm ci and npm run build will need to complete successfully for the build to succeed, but the
48+
composer run some-script is prepended by @ so if it fails, the build will continue forward.

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_provide_info__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Config
2424
{
2525
"build": [],
2626
"build_dev": [],
27+
"workflows": {},
2728
"checks": {
2829
"tbd": {
2930
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_provide_info_with_distignore__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Config
2424
{
2525
"build": [],
2626
"build_dev": [],
27+
"workflows": {},
2728
"checks": {
2829
"tbd": {
2930
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_provide_info_with_distinclude__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Config
2424
{
2525
"build": [],
2626
"build_dev": [],
27+
"workflows": {},
2728
"checks": {
2829
"tbd": {
2930
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_provide_info_with_gitattributes__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Config
2424
{
2525
"build": [],
2626
"build_dev": [],
27+
"workflows": {},
2728
"checks": {
2829
"tbd": {
2930
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_provide_info_with_puprc__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Config
2626
"ls -a"
2727
],
2828
"build_dev": [],
29+
"workflows": {},
2930
"checks": {
3031
"tbd": {
3132
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/InfoCest__it_should_show_invalid_puprc__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ Config
2424
{
2525
"build": [],
2626
"build_dev": [],
27+
"workflows": {},
2728
"checks": {
2829
"tbd": {
2930
"fail_method": "error",

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_fail_non_existent_workflow__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
The workflow 'whee' does not exist.

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_run_an_empty_workflow__0.snapshot.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Running bork workflow steps...

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_run_build_as_workflow__0.snapshot.txt

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Running build workflow steps...
2+
3+
> ls -a
4+
-------
5+
6+
.
7+
..
8+
.puprc
9+
bootstrap.php
10+
other-file.php
11+
package.json
12+
src
13+
14+
Workflow complete.
15+
16+
> echo "fake project, yo"
17+
-------------------------
18+
19+
fake project, yo
20+
21+
Workflow complete.

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_run_build_dev_as_workflow__0.snapshot.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Running build_dev workflow steps...
2+
3+
> echo "fake project, yo"
4+
-------------------------
5+
6+
fake project, yo
7+
8+
Workflow complete.

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_run_do__0.snapshot.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Running bork workflow steps...
2+
3+
> echo "fake project, yo"
4+
-------------------------
5+
6+
fake project, yo
7+
8+
Workflow complete.

‎tests/cli/Commands/__snapshots__/WorkflowCest__it_should_run_workflow__0.snapshot.txt

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Running bork workflow steps...
2+
3+
> echo "fake project, yo"
4+
-------------------------
5+
6+
fake project, yo
7+
8+
Workflow complete.

0 commit comments

Comments
 (0)
Please sign in to comment.