Skip to content

Commit 175848f

Browse files
ghinksbjohansebas
ghinks
and
bjohansebas
authored
Feature/documentation/raison detre (#112)
* feat: raise PR rationalize repeated nock code block into a beforeEach clause. * feat: raise PR Add some text to describe what wiby is as a prelude * feat: raise PR add a simple piece of graphics to see if that helps * docs: readme - make a simple example with screen shots available - create some text to give substance to why we have this tool * docs: readme - add callouts to cli - add callouts to PR raised * docs: readme - add wiby clean simple example * docs: readme - add wiby clean simple example, typo * docs: readme - wiby clean, grammar * docs: readme - wiby close-pr, interim push to look at github markup * docs: readme - wiby close-pr, add image showing PR is closed but branch remains * docs: readme - wiby validate , readme * docs: readme - wiby validate , typo in the URI * feat: docs Add the wiby result command to the readme. * feat: docs typos * feat: docs add links to the 5 examples given * feat: docs add a bit more to explain why we have wiby. * feat: docs add links to example repos * fix: array sz zero handling the array length needs to be checked as an array that is empty will be returned by the reduce and promise all combination * fix: undo checkin on incorrect branch undo checkin on incorrect branch. * run generate-usage --------- Co-authored-by: Sebastian Beltran <[email protected]>
1 parent f3e9967 commit 175848f

11 files changed

+241
-5
lines changed

‎README.md

Lines changed: 241 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,37 @@
1-
# wiby
1+
# WIBY (**W**ill **I** **B**reak **Y**ou)
22

3-
"Will I break you" - a tool for testing dependents
3+
A tool for testing dependents
44

55
This repository is managed by the [Package Maintenance Working Group](https://github.com/nodejs/package-maintenance), see [Governance](https://github.com/nodejs/package-maintenance/blob/master/Governance.md).
66

7+
## Purpose
8+
Wiby is a tool that will inform and trigger actions on a package to notify it that a registered dependency change may break
9+
it. This is different from triggering tests once a dependency has been published. The goal is to inform before publication.
10+
This will answer the question, "will I break you?", not "did I break you?".
11+
12+
The most basic notification of a change in a dependency will be a PR raised in the the dependent repository.
13+
14+
Wiby provides 5 basic commands test, clean, close, validate & result. The tool is intended to provide maintainers with a
15+
mechanism to both test and inform dependents of possible future breakages.
16+
17+
### Terminology
18+
The term **depenedent** shall mean an npm package that consumes another npm package, called a **dependency**, directly
19+
or indirectly via a tree of reliance through the package.json file. The **wiby** program exists to create a notification to the *dependent*
20+
package maintainers of changes made in a dependency. The **WIBY** program, when configured correctly, will raise a Pull
21+
Request against the dependent package informing of the change. The **intent** is to provide a notification of possible
22+
breakages of the dependent due to reliance on a dependency. No distinction is made between dev and non-dev dependencies.
23+
They are all dependencies that could break "the-example-dependent" in some operational or test manner. It is noted that
24+
in general dependent and dependencies are modules they can equally be repositories. For the purpose of this readme examples
25+
use github.
26+
27+
![Dependent Dependency Relationship](./images/Dependent-Dependency-Relationship.png)
28+
729
## Pre-requisites
830

931
### Github Token
1032

11-
wiby requires an environment variable `GITHUB_TOKEN` set to a Github access token. This token needs to be granted push permissions to the dependent repos.
33+
wiby requires an environment variable `GITHUB_TOKEN` set to a Github access token. This token needs to be granted push
34+
permissions to the dependent repos.
1235

1336
Example: `export GITHUB_TOKEN=XXXXX`
1437

@@ -32,6 +55,219 @@ Example:
3255

3356
## Available commands
3457

35-
[wiby test](./USAGE.md#wiby-test) Test your dependents
58+
[wiby test](./USAGE.md#wiby-test) Test your dependents
59+
60+
[wiby clean](./USAGE.md#wiby-clean) Clean (delete) a PR raised by Wiby
61+
62+
[wiby close_pr](./USAGE.md#wiby-test) Close a PR that was raised by Wiby and successfully run
63+
64+
[wiby validate](./USAGE.md#wiby-validate) Test the validity of the json in the .wiby.json file
65+
66+
[wiby result](./USAGE.md#wiby-result) Fetch the results of your tests
67+
68+
## Development
69+
70+
- This repository uses `semantic-release` with default configuration.
71+
- Create a new release by running `npx semantic-release`.
72+
## Examples
73+
74+
- [wiby test](#example-1)
75+
- [wiby clean](#example-2)
76+
- [wiby close-pr](#example-3)
77+
- [wiby validate](#example-4)
78+
- [wiby result](#example-5)
79+
80+
81+
In the examples the dependent npm package has the following package.json file. From this it is clear it has a dependency
82+
on an example called [example-dependency-id-a](https://github.com/ghinks/example-dependency-id-a). The examples given
83+
will show how to configure wiby so that the dependency "example-dependency-id-a" will be able to inform the dependent,
84+
[example-dependent-id-a](https://github.com/ghinks/example-dependent-id-a), of prospective issues.
85+
86+
```json
87+
{
88+
"name": "example-dependent-id-a",
89+
"version": "1.0.0",
90+
"main": "index.js",
91+
"scripts": {
92+
"test": "tap test.js"
93+
},
94+
"repository": {
95+
"type": "git",
96+
"url": "git+https://github.com/ghinks/example-dependent-id-a.git"
97+
},
98+
"license": "ISC",
99+
"bugs": {
100+
"url": "https://github.com/ghinks/example-dependent-id-a/issues"
101+
},
102+
"homepage": "https://github.com/ghinks/example-dependent-id-a#readme",
103+
"devDependencies": {
104+
"tap": "^15.1.2"
105+
},
106+
"dependencies": {
107+
"@gvhinks/example-dependency-id-a": "^0.0.0-development"
108+
}
109+
}
110+
```
111+
In this simple case the **dependent** package is called "example-dependent-id-a" and the dependencies are
112+
* tap
113+
* @gvhinks/example-dependency-id-a
114+
115+
If WIBY were configured in the dependencies **@gvhinks/example-dependency-id-a** then changes in the that
116+
dependency would raise a Pull Request agaist the "example-dependent-id-a" when the WIBY command was run within this
117+
repository.
118+
119+
### <a id="example-1"></a>Example 1 wiby test, simply dependent breakage check run locally
120+
The following is the most simple use case for *wiby test*. Given a dependent, example-dependent-id-a, and its dependency
121+
example-dependency-id-a the following steps are required to raise a notification against the dependent of changes in the
122+
dependency.
123+
124+
- install wiby as a dependency of example-dependency-id-a
125+
- create the .wiby.json configuration file
126+
- ensure that GITHUB_TOKEN is exported
127+
- run wiby test in the dependency example-dependency-id-a
128+
129+
This will raise a PR against the dependent configured in the .wiby.json configuration file. It is also possible to use
130+
wiby with command line arguments and this will be shown in a subsequent example.
131+
132+
#### Step #1 Install Wiby
133+
```shell
134+
npm i wiby -D
135+
```
136+
137+
#### Step #2 create the .wiby.json configuration file
138+
139+
```shell
140+
echo '{
141+
"dependents": [
142+
{
143+
"repository": "https://github.com/ghinks/example-dependent-id-a.git",
144+
"pullRequest": true
145+
}
146+
]
147+
} ' > .wiby.json
148+
```
149+
This means that example-dependency-id-a knows that upstream example-dependent-id-a consumes it.
150+
151+
#### Step #3 ensure GITHUB_TOKEN is exported
152+
153+
```shell
154+
export GITHUB_TOKEN=XXXXX
155+
```
156+
157+
#### Step #4 Run Wiby locally
158+
159+
```shell
160+
wiby test
161+
```
162+
163+
![Wiby Test Cli Command Output](./images/wiby-test-cli-with-callouts.png)
164+
165+
This raises a PR against the dependent as specified in the ".wiby.json" file
166+
167+
![Example PR raised by Wiby on Dependent](./images/PR-from-wiby-with-callouts.png)
168+
169+
It is to be noted that this example only uses one dependent object in the dependents array. The intent is that
170+
many dependents may be tested in a real world scenario.
171+
172+
### <a id="example-2"></a>Example 2 *Wiby Clean*
173+
174+
The *Wiby Test* command results in a PR being raised on the dependent package. The opposite of raising a PR would be to
175+
delete a PR that has been previously raised by *Wiby*. The *wiby clean* command carries out this action. It removes a
176+
PR that was previously raised by running the *wiby test* command. Note that the PR is deleted no matter the state of the
177+
PR. Meaning the PR will be deleted if the tests passed or failed.
178+
179+
The following example demonstrates the use of *wiby clean* based upon the specified dependents in the ".wiby.json"
180+
configuration file. It is to be noted that command line arguments may also be used instead of the ".wiby.json" file.
181+
The PR raised in the dependent is identified using wiby's PR naming schema.
182+
183+
The following steps are required to run *wiby clean*
184+
- ensure that GITHUB_TOKEN is exported
185+
- run wiby clean in the dependency example-dependency-id-a
186+
187+
for this example it is assumed that the dependency "example-dependency-id-a" has a ".wiby.json" that contains
188+
189+
```json
190+
{
191+
"dependents": [
192+
{
193+
"repository": "https://github.com/ghinks/example-dependent-id-a.git",
194+
"pullRequest": true
195+
}
196+
]
197+
}
198+
```
199+
This means that example-dependency-id-a knows that upstream example-dependent-id-a consumes it.
200+
201+
When *wiby clean* is run. The parent dependency's PR, in this case example-dependency-id-a, is deleted.
202+
203+
![Wiby clean run on command line via .wiby.json file](./images/wiby-clean-example-on-cli.png)
204+
205+
206+
It is to be noted that this example only uses one dependent object in the dependents array. The intent is that
207+
many dependents may be cleaned in a real world scenario.
208+
209+
### <a id="example-3"></a>Example 3 Wiby close-pr
210+
When tests have been run successfully by wiby you can close the raised PRs with the wiby close pr command. The same
211+
pre-requisite of having a GITHUB_TOKEN applies.
212+
213+
- ensure that GITHUB_TOKEN is exported
214+
- run wiby close-pr
215+
216+
```shell
217+
wiby close-pr
218+
```
219+
220+
Only those tests that have passed successfully will have their PRs closed.
221+
222+
![Wiby close-pr command line via .wiby.json file](./images/wiby-close-pr-cli.png)
223+
224+
The close-pr command does delete the branch that was used to create the pull request.
225+
226+
### <a id="example-4"></a>Example 4 Wiby validate
227+
The although you can pass command line arguments to wiby the *.wiby.json* file is envisioned as the primary automation
228+
configuration file. The *.wiby.json* file has a particular schema which is enforced. To validate your *.wiby.json* file
229+
run the *wiby validate* command in the directory with your *.wiby.json* file.
230+
231+
The validation is based upon the schema.
232+
233+
```shell
234+
wiby validate
235+
```
236+
This will validate the .wiby.json file. Or the command
237+
238+
```shell
239+
wiby validate --config other-config.json
240+
```
241+
Will validate a file of another name for the schema below.
242+
243+
```json
244+
"dependents": [
245+
{
246+
"repository": "https://github.com/some/repo"
247+
"pullRequest": true
248+
}
249+
]
250+
```
251+
The repository field must be a valid URI with protocols
252+
- https
253+
- git
254+
- git+https
255+
256+
### <a id="example-5"></a>Example 5 Wiby Result
257+
258+
When a wiby test is run the resulting PR raised will trigger the automated testing in the dependent's CI system. The
259+
status of the PR raised by wiby can be interrogated using the **wiby result** command. This will fetch the status of
260+
the PR back to the command line.
261+
262+
- ensure that GITHUB_TOKEN is exported
263+
- run wiby close-pr
264+
265+
Immediately the wiby test command is run the
266+
267+
![wiby result before PR completes tests](./images/wiby-result-queued.png)
268+
269+
After the tests have been queued the results will show that the checks are null.
270+
271+
![wiby result after PR tests complete](./images/wiby-result-success.png)
36272

37-
[wiby result](./USAGE.md#wiby-result) Fetch the results of your tests
273+
After the tests have run the results will show that the checks are successful.

‎images/Dependent-Dependency-Relationship.png

88.1 KB
Loading

‎images/PR-from-wiby-with-callouts.png

497 KB
Loading

‎images/github-pr-raised-from-wiby-test-command.png

463 KB
Loading

‎images/wiby-clean-example-on-cli.png

374 KB
Loading

‎images/wiby-clean-explanation.png

619 KB
Loading

‎images/wiby-close-pr-cli.png

223 KB
Loading

‎images/wiby-result-queued.png

152 KB
Loading

‎images/wiby-result-success.png

153 KB
Loading

‎images/wiby-test-cli-screenshot.png

158 KB
Loading

0 commit comments

Comments
 (0)