Merge pull request #593 from rico-chet/update-negation-recommendation

docs/gotchas: Update recommendation for negative statements

docs/CHANGELOG.md

@@ -8,6 +8,15 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
 [kac]: https://keepachangelog.com/en/1.0.0/
 [semver]: https://semver.org/
 
+## [Unreleased]
+
+### Added
+
+#### Documentation
+
+* update gotcha about negated statements: Recommend using `run !` on Bats
+  versions >=1.5.0 (#593)
+
 ## [1.7.0] - 2022-05-14
 
 ### Added

docs/source/gotchas.rst

@@ -12,10 +12,11 @@ Please adhere to this idiom while using bats, or you will constantly work agains
 My negated statement (e.g. ! true) does not fail the test, even when it should.
 -------------------------------------------------------------------------------
 
-Bash deliberately excludes negated return values from causing a pipeline to exit (see bash's `-e` option). You'll need to use the form `! x || false` or (recommended) use `run` and check for `[ $status != 0 ]`.
+Bash deliberately excludes negated return values from causing a pipeline to exit (see bash's `-e` option).
+Use `run !` on Bats 1.5.0 and above. For older bats versions, use one of `! x || false` or `run` with `[ $status != 0 ]`.
 
 If the negated command is the final statement in a test, that final statement's (negated) exit status will propagate through to the test's return code as usual.
-Negated statements of the form `! x || false` will explicitly fail the test when the pipeline returns true, regardless of where they occur in the test.
+Negated statements of one of the correct forms mentioned above will explicitly fail the test when the pipeline returns true, regardless of where they occur in the test.
 
 I cannot register a test multiple times via for loop.
 -----------------------------------------------------