Skip to content

Commit 5439552

Browse files
deecewanbestander
deecewan
authored and
bestander
committed
add RFC for script run hooks (#70)
1 parent c1112fb commit 5439552

File tree

1 file changed

+196
-0
lines changed

1 file changed

+196
-0
lines changed

‎text/0000-update-hook-runs.md

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
- Start Date: 2017-06-19
2+
- RFC PR:
3+
- Yarn Issue:
4+
5+
# Summary
6+
7+
Bring the scripts that run on certain commands closer to parity with NPM.
8+
9+
# Motivation
10+
11+
There are a few changes to the scripts hooks that NPM has made recently, and it
12+
would be good to bring `yarn` to the same standard.
13+
14+
This means that `yarn` can remove hooks that don't make sense, and stop
15+
supporting issues brought up by people confused about *why* a certain script is
16+
running.
17+
18+
Additionally, by tracking closely to what NPM is doing with their hooks, `yarn`
19+
remains a drop-in replacement, as most people expect it to act.
20+
21+
# Detailed design
22+
23+
### State of Scripts
24+
25+
Below are all the scripts that NPM currently auto-runs, and at which points they
26+
run. Currently, there is only one deprecation that motivated this RFC, but it is
27+
anticipated that there will be more in the long run.
28+
29+
This list is kind of long, because I've enumerated all options.
30+
31+
- `prepublish`
32+
- before `publish`
33+
- before `install`
34+
- *Note: this is the deprecation. `prepublish` will no longer run on
35+
install*
36+
- This hook should *not* be added, as it is removed as of `npm@5`.
37+
- `prepare`
38+
- before `publish`
39+
- before `install`
40+
- *Note: This is the replacement for the current `prepublish` behaviour.*
41+
- `prepublishOnly`
42+
- before `publish`
43+
- `prepack`
44+
- before `pack`
45+
- before `publish`
46+
- `postpack`
47+
- after `pack`
48+
- after `publish`
49+
- `publish`
50+
- after `publish`
51+
- confusing, but runs *after* the package has been published.
52+
- `postpublish`
53+
- after `publish`
54+
- `preinstall`
55+
- before `install`
56+
- `install`
57+
- after `install`
58+
- confusing, but runs *after* the package has been installed.
59+
- `postinstall`
60+
- after `install`
61+
- `preuninstall`
62+
- before `uninstall`
63+
- `uninstall`
64+
- before `uninstall`
65+
- confusing, but runs *before* the package is uninstalled
66+
- `postuninstall`
67+
- after `uninstall`
68+
- `preversion`
69+
- before `version`
70+
- `version`
71+
- after `version`
72+
- runs *before* the version commit is made
73+
- `postversion`
74+
- after `version`
75+
- runs *after* the version commit is made
76+
- `preshrinkwrap`
77+
- before `shrinkwrap`
78+
- `shrinkwrap`
79+
- before `shrinkwrap`
80+
- confusing, but runs *before* the shrinkwrap is created
81+
- I'm not sure `yarn` needs to include this, given that `shrinkwrap` is not
82+
implemented.
83+
- `postshrinkwrap`
84+
- after `shrinkwrap`
85+
86+
The following commands are backed by user-written scripts. The `pre` and `post`
87+
commands are run before and after the user-written version, and there is no
88+
built-in run.
89+
90+
*Note: `test` has a built-in default of `echo 'Error: no test specified'`, so
91+
the `pre` and `post` will run regardless*
92+
93+
*Note: all other scripts will error, and no hook will run, except `restart`
94+
(explained below).*
95+
96+
- `pretest`
97+
- before `test`
98+
- `posttest`
99+
- after `test`
100+
- `prestop`
101+
- before `stop`
102+
- `poststop`
103+
- after `stop`
104+
- `prestart`
105+
- before `start`
106+
- `poststart`
107+
- after `start`
108+
- `prerestart`
109+
- before `restart`
110+
- `postrestart`
111+
- after `restart`
112+
113+
`restart` is a special case, because it will run the `stop` and then the `start`
114+
scripts if `restart` doesn't exist. It doesn't throw an error if any of those
115+
scripts are not defined. Interestingly, it will run the `pre`- and `post`-
116+
scripts for `stop` and `start`, even if `stop` and `start` themselves are not
117+
defined.
118+
119+
### Multiple Hooks, One Command
120+
121+
There are some commands that have *multiple* hooks attached to them. These hooks
122+
will run in a certain order.
123+
124+
#### restart
125+
126+
`restart` is arguabled the most confusing behavior. First, let's look at the
127+
behaviour when no `restart` script is defined.
128+
129+
Regardless of the definition of the actual `start` and `stop` commands,
130+
`restart` will run the lifecycle hooks. If all lifecycle hooks are defined, the
131+
scripts are run in the following order. If a particular script is not defined,
132+
it is simply skipped.
133+
134+
`prerestart` -> `prestop` -> `poststop` -> `prestart` -> `poststart` ->
135+
`postrestart`
136+
137+
This makes more sense when you look at the fact the `restart` runs `stop`, and
138+
then `start` if there is no `restart`. It makes less sense that these hooks are
139+
run if there is no `stop` or `start`, even though running `start` will error,
140+
and run no hooks if `start` is not defined.
141+
142+
If `restart` is defined, the hooks are run like:
143+
144+
`prerestart` -> `restart` -> `postrestart`
145+
146+
#### publish
147+
148+
Due to the addition of the extra hooks to try and solve the confusion around the
149+
`publish` hook, the hooks are run in the following order:
150+
151+
`prepublish` -> `prepare` -> `prepublishOnly`
152+
153+
In practice, the `prepublishOnly` event may be dropped at any time, so this hook
154+
ordering makes little-to-no sense, given that `prepublishOnly` now has the same
155+
behaviour as `publish`, yet they on different sides of `prepare`.
156+
157+
The current proposal would be to match the existing behaviour of `npm`. That
158+
will also require changing the current `yarn` behaviour, as `prestart` and
159+
`poststart` scripts currently run, even without a `start` defined.
160+
161+
# How We Teach This
162+
163+
This is a continuation of both `npm` patterns and existing `yarn` patterns. I
164+
think that this could also be cleared up by displaying what hooks will be run at
165+
the commencement, so that people can clearly see what is going to happen.
166+
167+
E.g.
168+
169+
```
170+
> yarn start
171+
Running prestart -> start -> poststart
172+
```
173+
174+
And show only the hooks that get run, and what order they'll be run in.
175+
176+
# Drawbacks
177+
178+
- It will cause changes to the current `yarn` behaviour of running hooks even if
179+
no script is defined
180+
- e.g. `prestart` and `poststart` run, even without `start` being present.
181+
`npm` throws an error.
182+
- It may change peoples existing workflows if they expect `prepublish` to run on
183+
`install`
184+
- However, this change brings `yarn` into line with `npm`
185+
186+
# Alternatives
187+
188+
- Split away from current `npm` behaviour
189+
- This gives `yarn` the option to define behaviours in a more modern way, and
190+
the flexibility to change when/how hooks run
191+
- Leave the current behaviour as-is
192+
193+
# Unresolved questions
194+
195+
- How to display this change to users?
196+
- Where to keep a list of hooks and what orders they run in?

0 commit comments

Comments
 (0)