added failure documentation

docs/docs/logging.html

@@ -28,12 +28,26 @@
               }
             });
         </script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/kenotron/build-rig/tree/master/packages/documentation/docs/logging.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Logging</h1></header><article><div><span><p><code>build-rig</code> is simple, but it is opinionated. One of the built-in capabilities of <code>build-rig</code> is logging. We feel that this is an important enough of a feature to be available inside a task within its own context.</p>
+<p>Typically, logging tasks look like the following:</p>
+<p><img src="/build-rig/docs/assets/typical.png" alt=""></p>
 <h2><a class="anchor" aria-hidden="true" id="usage"></a><a href="#usage" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Usage</h2>
 <p>To log within the task, simply use the <code>logger</code> object off of <code>this</code> inside a task function.</p>
 <pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
   <span class="hljs-keyword">this</span>.logger.info(<span class="hljs-string">'log something'</span>);
 });
 </code></pre>
+<p>If you want to log an error or warning do it with the <code>logger</code> object's <code>warn()</code> and <code>error()</code> functions. It looks like this following:</p>
+<p><img src="/build-rig/docs/assets/failure.png" alt=""></p>
+<pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
+  <span class="hljs-keyword">this</span>.logger.warn(<span class="hljs-string">'a warning'</span>);
+  <span class="hljs-keyword">this</span>.logger.error(<span class="hljs-string">'an error'</span>);
+});
+</code></pre>
+<p>If your error is meant to stop the tasks, simply throw an Error:</p>
+<pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
+  <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'an error'</span>);
+});
+</code></pre>
 <h2><a class="anchor" aria-hidden="true" id="next-steps"></a><a href="#next-steps" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Next Steps</h2>
 <p>Learn about processing <a href="/build-rig/docs/args">arguments from command line</a></p>
 </span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="/build-rig/docs/composition"><span class="arrow-prev">← </span><span>Composition of tasks</span></a><a class="docs-next button" href="/build-rig/docs/args"><span>Command line arguments</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#usage">Usage</a></li><li><a href="#next-steps">Next Steps</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="copyright">Copyright © 2018</section></footer></div></body></html>

docs/docs/logging/index.html

@@ -28,12 +28,26 @@
               }
             });
         </script></nav></div><div class="container mainContainer"><div class="wrapper"><div class="post"><header class="postHeader"><a class="edit-page-link button" href="https://github.com/kenotron/build-rig/tree/master/packages/documentation/docs/logging.md" target="_blank" rel="noreferrer noopener">Edit</a><h1 class="postHeaderTitle">Logging</h1></header><article><div><span><p><code>build-rig</code> is simple, but it is opinionated. One of the built-in capabilities of <code>build-rig</code> is logging. We feel that this is an important enough of a feature to be available inside a task within its own context.</p>
+<p>Typically, logging tasks look like the following:</p>
+<p><img src="/build-rig/docs/assets/typical.png" alt=""></p>
 <h2><a class="anchor" aria-hidden="true" id="usage"></a><a href="#usage" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Usage</h2>
 <p>To log within the task, simply use the <code>logger</code> object off of <code>this</code> inside a task function.</p>
 <pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
   <span class="hljs-keyword">this</span>.logger.info(<span class="hljs-string">'log something'</span>);
 });
 </code></pre>
+<p>If you want to log an error or warning do it with the <code>logger</code> object's <code>warn()</code> and <code>error()</code> functions. It looks like this following:</p>
+<p><img src="/build-rig/docs/assets/failure.png" alt=""></p>
+<pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
+  <span class="hljs-keyword">this</span>.logger.warn(<span class="hljs-string">'a warning'</span>);
+  <span class="hljs-keyword">this</span>.logger.error(<span class="hljs-string">'an error'</span>);
+});
+</code></pre>
+<p>If your error is meant to stop the tasks, simply throw an Error:</p>
+<pre><code class="hljs css language-js">task(<span class="hljs-string">'needsLogging'</span>, <span class="hljs-function"><span class="hljs-keyword">function</span>(<span class="hljs-params"></span>) </span>{
+  <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">'an error'</span>);
+});
+</code></pre>
 <h2><a class="anchor" aria-hidden="true" id="next-steps"></a><a href="#next-steps" aria-hidden="true" class="hash-link"><svg class="hash-link-icon" aria-hidden="true" height="16" version="1.1" viewBox="0 0 16 16" width="16"><path fill-rule="evenodd" d="M4 9h1v1H4c-1.5 0-3-1.69-3-3.5S2.55 3 4 3h4c1.45 0 3 1.69 3 3.5 0 1.41-.91 2.72-2 3.25V8.59c.58-.45 1-1.27 1-2.09C10 5.22 8.98 4 8 4H4c-.98 0-2 1.22-2 2.5S3 9 4 9zm9-3h-1v1h1c1 0 2 1.22 2 2.5S13.98 12 13 12H9c-.98 0-2-1.22-2-2.5 0-.83.42-1.64 1-2.09V6.25c-1.09.53-2 1.84-2 3.25C6 11.31 7.55 13 9 13h4c1.45 0 3-1.69 3-3.5S14.5 6 13 6z"></path></svg></a>Next Steps</h2>
 <p>Learn about processing <a href="/build-rig/docs/args">arguments from command line</a></p>
 </span></div></article></div><div class="docs-prevnext"><a class="docs-prev button" href="/build-rig/docs/composition"><span class="arrow-prev">← </span><span>Composition of tasks</span></a><a class="docs-next button" href="/build-rig/docs/args"><span>Command line arguments</span><span class="arrow-next"> →</span></a></div></div></div><nav class="onPageNav"><ul class="toc-headings"><li><a href="#usage">Usage</a></li><li><a href="#next-steps">Next Steps</a></li></ul></nav></div><footer class="nav-footer" id="footer"><section class="copyright">Copyright © 2018</section></footer></div></body></html>

packages/build-rig/example/rig.fail.js

@@ -1,21 +1,29 @@
 const { task, series, parallel } = require('../lib/index');
 
-task('done', function(done) {
-  this.logger.info('args_done: ', this.argv);
-  setTimeout(done, 500);
+task('clean', function() {
+  this.logger.info('Cleaning up the build and lib and dist folders');
 });
 
-task('ctxonly', { describe: 'ctx coolness', builder: yargs => yargs.option('name') }, function() {
-  this.logger.info('ctxonly');
-  this.logger.info(JSON.stringify(this.argv));
+task('ts', function() {
+  this.logger.info('Here we can run build steps like Babel or Typescript');
+});
+
+task('warn', function() {
   this.logger.warn('This is what a warning looks like');
-  throw new Error('intentionally fail');
 });
 
-task('async', async function() {
-  this.logger.info(await Promise.resolve('async'));
+task('fail', function() {
+  throw new Error('this is an intentional error');
 });
 
-task('default', parallel('done', 'ctxonly', series('async')));
+task('tslint', function() {
+  this.logger.info('Linting with tslint');
+});
 
-task('yes', series('default'));
+task('webpack', function() {
+  this.logger.info('Webpack bundling files');
+});
+
+task('build', parallel('tslint', series('clean', 'ts', 'webpack', 'warn', 'fail')));
+
+task('default', parallel('build'));

packages/build-rig/src/undertaker.ts

@@ -41,7 +41,7 @@ undertaker.on('error', function(args: any) {
     taskLogger(args.name).error(chalk.yellow('------------------------------------'));
     taskLogger(args.name).error(chalk.yellow(args.error));
     taskLogger(args.name).error(chalk.yellow('------------------------------------'));
-  } else {
+  } else if (!args.branch) {
     taskLogger(args.name).error(chalk.dim(`Error previously detected. See above for error messages.`));
   }
 

packages/documentation/docs/logging.md

@@ -6,6 +6,10 @@ sidebar_label: Logging
 
 `build-rig` is simple, but it is opinionated. One of the built-in capabilities of `build-rig` is logging. We feel that this is an important enough of a feature to be available inside a task within its own context.
 
+Typically, logging tasks look like the following:
+
+![](assets/typical.png)
+
 ## Usage
 
 To log within the task, simply use the `logger` object off of `this` inside a task function.
@@ -16,6 +20,25 @@ task('needsLogging', function() {
 });
 ```
 
+If you want to log an error or warning do it with the `logger` object's `warn()` and `error()` functions. It looks like this following:
+
+![](assets/failure.png)
+
+```js
+task('needsLogging', function() {
+  this.logger.warn('a warning');
+  this.logger.error('an error');
+});
+```
+
+If your error is meant to stop the tasks, simply throw an Error:
+
+```js
+task('needsLogging', function() {
+  throw new Error('an error');
+});
+```
+
 ## Next Steps
 
 Learn about processing [arguments from command line](args.md)