Merge pull request #178 from oddbird/doc-updates

Doc updates

.github/workflows/codeql-analysis.yml

@@ -1,8 +1,8 @@
-name: "CodeQL"
+name: 'CodeQL'
 
 on:
   push:
-    branches: [main, ]
+    branches: [main]
   pull_request:
     # The branches below must be a subset of the branches above
     branches: [main]
@@ -15,40 +15,40 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v2
-      with:
-        # We must fetch at least the immediate parents so that if this is
-        # a pull request then we can checkout the head.
-        fetch-depth: 2
-
-    # If this run was triggered by a pull request event, then checkout
-    # the head of the pull request instead of the merge commit.
-    - run: git checkout HEAD^2
-      if: ${{ github.event_name == 'pull_request' }}
-
-    # Initializes the CodeQL tools for scanning.
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v1
-      # Override language selection by uncommenting this and choosing your languages
-      with:
-        languages: javascript
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v1
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 https://git.io/JvXDl
-
-    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
-    #    and modify them (or add more) to build your code if your project
-    #    uses a compiled language
-
-    #- run: |
-    #   make bootstrap
-    #   make release
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v1
+      - name: Checkout repository
+        uses: actions/checkout@v2
+        with:
+          # We must fetch at least the immediate parents so that if this is
+          # a pull request then we can checkout the head.
+          fetch-depth: 2
+
+      # If this run was triggered by a pull request event, then checkout
+      # the head of the pull request instead of the merge commit.
+      - run: git checkout HEAD^2
+        if: ${{ github.event_name == 'pull_request' }}
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        # Override language selection by uncommenting this and choosing your languages
+        with:
+          languages: javascript
+
+      # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below)
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v1
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 https://git.io/JvXDl
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+      #    and modify them (or add more) to build your code if your project
+      #    uses a compiled language
+
+      #- run: |
+      #   make bootstrap
+      #   make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1

README.md

@@ -4,19 +4,6 @@
 [![Coverage Status](https://coveralls.io/repos/github/oddbird/true/badge.svg?branch=main)](https://coveralls.io/github/oddbird/true?branch=main)
 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
-True is a unit-testing tool
-for [Sass](https://sass-lang.com/) code –
-initially developed for the
-[Susy layout toolkit](https://www.oddbird.net/susy/).
-All of the test code is written in plain Sass,
-and can be compiled using Dart Sass –
-but we also provide integration with
-JavaScript test runners
-(e.g. [Mocha](https://mochajs.org/) or [Jest](https://jestjs.io/)),
-for extra features and improved reporting.
-
-**Verb**
-
 1. To make true; shape, adjust, place, etc., exactly or accurately:
 
    _True the wheels of a bicycle after striking a pothole._
@@ -29,6 +16,25 @@ for extra features and improved reporting.
 
    _True your sweet plugin before you deploy._
 
+True is a unit-testing tool
+for [Sass](https://sass-lang.com/) code.
+All of the tests are written in plain Sass,
+and can be compiled using Dart Sass –
+but we also provide integration with
+JavaScript test runners
+(e.g. [Mocha](https://mochajs.org/) or [Jest](https://jestjs.io/)),
+for extra features and improved reporting.
+
+_Note that **Node Sass**
+is several years behind **Dart Sass**
+and the official Sass specification.
+It will soon be
+[deprecated entirely](https://github.com/sass/node-sass/issues/2952),
+so we've decided to move forward
+with the latest Sass features,
+and **no longer support Node Sass
+in any new (4.0+) releases**._
+
 ## Install
 
 In command line:

docs/api-errors.html

@@ -804,6 +804,20 @@ <h2 class="item-title">
 the function will output errors as comments without stopping compilation.
 This can be used to test errors as return values with True,
 or to “catch” errors and handle them in different<span class="widont">&nbsp;</span>ways.</p>
+<p>Since True results rely on completing compilation,
+we do not have a way to “error out” of the code being tested.
+If there is code that needs to be skipped after an error,
+we recommend using explicit Sass conditional (if/else) statements
+to avoid compounding the<span class="widont">&nbsp;</span>problem:</p>
+<pre><code class="lang-scss"> @mixin width ($length) {
+   @if (meta.type-of($length) != number) {
+     @include true.error(&quot;$length must be a number&quot;, &quot;width&quot;, true);
+   @else {
+     // The @else block hides any remaining output
+     width: $length;
+   }
+ }
+</code></pre>
 
 
 

docs/index.html

@@ -183,17 +183,6 @@ <h1 id="true">True</h1>
 <p><a href="https://travis-ci.org/oddbird/true"><img src="https://travis-ci.org/oddbird/true.svg?branch=main" alt="Build Status"></a>
 <a href="https://coveralls.io/github/oddbird/true?branch=main"><img src="https://coveralls.io/repos/github/oddbird/true/badge.svg?branch=main" alt="Coverage Status"></a>
 <a href="https://opensource.org/licenses/BSD-3-Clause"><img src="https://img.shields.io/badge/License-BSD%203--Clause-blue.svg" alt="License"></a></p>
-<p>True is a unit-testing tool
-for <a href="https://sass-lang.com/">Sass</a> code –
-initially developed for the
-<a href="https://www.oddbird.net/susy/">Susy layout toolkit</a>.
-All of the test code is written in plain Sass,
-and can be compiled using Dart Sass –
-but we also provide integration with
-JavaScript test runners
-(e.g. <a href="https://mochajs.org/">Mocha</a> or <a href="https://jestjs.io/">Jest</a>),
-for extra features and improved<span class="widont">&nbsp;</span>reporting.</p>
-<p><strong>Verb</strong></p>
 <ol>
 <li>
 <p>To make true; shape, adjust, place, etc., exactly or<span class="widont">&nbsp;</span>accurately:</p>
@@ -208,6 +197,23 @@ <h1 id="true">True</h1>
 <p><em>True your sweet plugin before you<span class="widont">&nbsp;</span>deploy.</em></p>
 </li>
 </ol>
+<p>True is a unit-testing tool
+for <a href="https://sass-lang.com/">Sass</a> code.
+All of the tests are written in plain Sass,
+and can be compiled using Dart Sass –
+but we also provide integration with
+JavaScript test runners
+(e.g. <a href="https://mochajs.org/">Mocha</a> or <a href="https://jestjs.io/">Jest</a>),
+for extra features and improved<span class="widont">&nbsp;</span>reporting.</p>
+<p><em>Note that <strong>Node Sass</strong>
+is several years behind <strong>Dart Sass</strong>
+and the official Sass specification.
+It will soon be
+<a href="https://github.com/sass/node-sass/issues/2952">deprecated entirely</a>,
+so we’ve decided to move forward
+with the latest Sass features,
+and <strong>no longer support Node Sass
+in any new (4.0+)<span class="widont">&nbsp;</span>releases</strong>.</em></p>
 <h2 id="install">Install</h2>
 <p>In command line:</p>
 <pre><code class="lang-bash">npm install sass-true

sass/config/_throw.scss

@@ -83,6 +83,24 @@ $catch-errors: false !default;
 /// the function will output errors as comments without stopping compilation.
 /// This can be used to test errors as return values with True,
 /// or to "catch" errors and handle them in different ways.
+///
+/// Since True results rely on completing compilation,
+/// we do not have a way to "error out" of the code being tested.
+/// If there is code that needs to be skipped after an error,
+/// we recommend using explicit Sass conditional (if/else) statements
+/// to avoid compounding the problem:
+///
+/// ```scss
+///  @mixin width ($length) {
+///    @if (meta.type-of($length) != number) {
+///      @include true.error("$length must be a number", "width", true);
+///    @else {
+///      // The @else block hides any remaining output
+///      width: $length;
+///    }
+///  }
+/// ```
+///
 /// @access public
 /// @group api-errors
 /// @since v6.0