docs: include a warning about surprising not-exists behavior (#979)

## Which problem is this PR solving?

- Partially addresses #965 "not-exists is a footgun" 

## Short description of the changes

- Update rulesMeta description for the Condition Operator to include a
warning about using `not-exists` in a rule without also scoping that
rule to "span".

---------

Co-authored-by: Kent Quirk <[email protected]>
Co-authored-by: Faith Chikwekwe <[email protected]>
Co-authored-by: Mary J <[email protected]>

RELEASING.md

@@ -3,7 +3,9 @@
 1. Check that licenses are current with `make verify-licenses`
 2. Regenerate documentation with `make all` from within the `tools/convert` folder. If there have
 been changes to `rules.md`, you may need to manually modify the `rules_complete.yaml` to reflect the same change.
-3. If either `refinery_config.md` or `refinery_rules.md` were modified in this release, you must also copy these files to [docs](https://github.com/honeycombio/docs) and do a docs PR. Address any feedback from the the docs team and apply that feedback back into this repo.
+3. If either `refinery_config.md` or `refinery_rules.md` were modified in this release, you must also open a [docs](https://github.com/honeycombio/docs) PR and update these files there under `subpages/refinery/` .
+   Replace the underscores (`_`) in the filenames with a dash (`-`) or the docs linter will be upset.
+   Address any feedback from the the docs team and apply that feedback back into this repo.
 4. After addressing any docs change, add release entry to [changelog](./CHANGELOG.md)
     - Use below command to get a list of all commits since last release
     ```

config/metadata/rulesMeta.yaml

@@ -651,6 +651,12 @@ groups:
         summary: is the comparison operator to use.
         description: >
           The comparison operator to use. String comparisons are case-sensitive.
+          For most cases, use negative operators (`!=`, `does-not-contain`, and
+          `not-exists`) in a rule with a scope of "span".
+          WARNING: Rules can have `Scope: trace` or `Scope: span`; a negative
+          operator with `Scope: trace` will be true if **any** single span in the
+          entire trace matches the negative condition.
+          This is almost never desired behavior.
       - name: Value
         type: anyscalar
         summary: is the value to compare against.

rules_conditions.md

@@ -116,6 +116,10 @@ Basic comparison -- `not equals`.
 The result is true if the value of the named `Field` is not equal to the `Value` specified.
 See [`Datatype`](#datatype) for how different datatypes are handled.
 
+For most cases, use `'!='` in a rule with a scope of "span".
+WARNING: Rules can have `Scope: trace` or `Scope: span`; `'!='` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition.
+This is almost never desired behavior.
+
 ### `'<'`
 
 Basic comparison -- `less than`.
@@ -161,6 +165,10 @@ Comparisons are case-sensitive and exact.
 
 Values are always coerced to strings -- the `Datatype` parameter is ignored.
 
+For most cases, use `does-not-contain` in a rule with a scope of "span".
+WARNING: Rules can have `Scope: trace` or `Scope: span`; `does-not-contain` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition.
+This is almost never desired behavior.
+
 ### `exists`
 
 Tests if the specified span contains the field named by the `Field` parameter, without considering its value.
@@ -173,6 +181,10 @@ Tests if the specified span does not contain the field named by the `Field` para
 
 Both the `Value` and the `Datatype` parameters are ignored.
 
+For most cases, use `not-exists` in a rule with a scope of "span".
+WARNING: Rules can have `Scope: trace` or `Scope: span`; `not-exists` used with `Scope: trace` will be true if **any** single span in the entire trace matches the negative condition.
+This is almost never desired behavior.
+
 ### `matches`
 
 Tests if the span value specified by the `Field` parameter matches the regular expression specified by the `Value` parameter.