Document hook scripts and best practices

Author: isaacs

doc/scripts.md

@@ -95,3 +95,34 @@ process.
 
 Note that these script files don't have to be nodejs or even javascript
 programs. They just have to be some kind of executable file.
+
+## HOOK SCRIPTS
+
+If you want to run a specific script at a specific lifecycle event for ALL
+packages, then you can use a hook script.
+
+Place an executable file at `{root}/.npm/.hooks/{eventname}`, and it'll get
+run for all packages when they are going through that point in the package
+lifecycle.
+
+Hook scripts are run exactly the same way as package.json scripts.  That is,
+they are in a separate child process, with the env described above.
+
+## BEST PRACTICES
+
+* Don't exit with a non-zero error code unless you *really* mean it.
+  Except for uninstall/deactivate scripts, this will cause the npm action
+  to fail, and potentially be rolled back.  If the failure is minor or
+  only will prevent some optional features, then it's better to just
+  print a warning and exit successfully.
+* Try not to use scripts to do what npm can do for you.  Read through
+  `npm help json` to see all the things that you can specify and enable
+  by simply describing your package appropriately.  In general, this will
+  lead to a more robust and consistent state.
+* Inspect the env to determine where to put things.  For instance, if
+  the `npm_config_binroot` environ is set to `/home/user/bin`, then don't
+  try to install executables into `/usr/local/bin`.  The user probably
+  set it up that way for a reason.
+* Don't prefix your script commands with "sudo".  If root permissions are
+  required for some reason, then it'll fail with that error, and the user
+  will sudo the npm command in question.

man/scripts.1

@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-SCRIPTS" "1" "August 2010" "" ""
+.TH "NPM\-SCRIPTS" "1" "September 2010" "" ""
 .
 .SH "NAME"
 \fBnpm-scripts\fR \-\- How npm handles the "scripts" field
@@ -148,3 +148,44 @@ process\.
 .P
 Note that these script files don\'t have to be nodejs or even javascript
 programs\. They just have to be some kind of executable file\.
+.
+.SH "HOOK SCRIPTS"
+If you want to run a specific script at a specific lifecycle event for ALL
+packages, then you can use a hook script\.
+.
+.P
+Place an executable file at \fB{root}/\.npm/\.hooks/{eventname}\fR, and it\'ll get
+run for all packages when they are going through that point in the package
+lifecycle\.
+.
+.P
+Hook scripts are run exactly the same way as package\.json scripts\.  That is,
+they are in a separate child process, with the env described above\.
+.
+.SH "BEST PRACTICES"
+.
+.IP "\(bu" 4
+Don\'t exit with a non\-zero error code unless you \fIreally\fR mean it\.
+Except for uninstall/deactivate scripts, this will cause the npm action
+to fail, and potentially be rolled back\.  If the failure is minor or
+only will prevent some optional features, then it\'s better to just
+print a warning and exit successfully\.
+.
+.IP "\(bu" 4
+Try not to use scripts to do what npm can do for you\.  Read through \fBnpm help json\fR to see all the things that you can specify and enable
+by simply describing your package appropriately\.  In general, this will
+lead to a more robust and consistent state\.
+.
+.IP "\(bu" 4
+Inspect the env to determine where to put things\.  For instance, if
+the \fBnpm_config_binroot\fR environ is set to \fB/home/user/bin\fR, then don\'t
+try to install executables into \fB/usr/local/bin\fR\|\.  The user probably
+set it up that way for a reason\.
+.
+.IP "\(bu" 4
+Don\'t prefix your script commands with "sudo"\.  If root permissions are
+required for some reason, then it\'ll fail with that error, and the user
+will sudo the npm command in question\.
+.
+.IP "" 0
+