Document GHC-56147

message-index/messages/GHC-56147/ignored-rule/after/IgnoredRule.hs

@@ -0,0 +1,6 @@
+{-# LANGUAGE Safe #-}
+module IgnoredRule where
+
+
+myId :: a -> a
+myId x = x

message-index/messages/GHC-56147/ignored-rule/before/IgnoredRule.hs

@@ -0,0 +1,6 @@
+{-# LANGUAGE Safe #-}
+module IgnoredRule where
+
+{-# RULES "myId" forall x. myId x = x #-}
+myId :: a -> a
+myId x = x

message-index/messages/GHC-56147/ignored-rule/index.md

@@ -0,0 +1,14 @@
+---
+title: Cannot add a rewrite rule for the identity function
+---
+
+Wanting to rewrite occurrences of `myId x` to `x` in programs is sensible. But since GHC cannot check in general whether rewrite rules violate the guarantees of SafeHaskell, GHC chooses to ignore all such rules in modules which are annotated as `Safe`.These rewrite rules should therefore be removed.
+
+```
+messages/GHC-56147/ignored-rule/before/IgnoredRule.hs:4:11: warning: [GHC-56147]
+    Rule "myId" ignored
+    Defining user rules is disabled under Safe Haskell
+  |
+4 | {-# RULES "myId" forall x. myId x = x #-}
+  |           ^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```

message-index/messages/GHC-56147/index.md

@@ -0,0 +1,10 @@
+---
+title: Rewrite rules are ignored in Safe Haskell
+summary: Rewrite rules are not allowed in Safe Haskell and are therefore ignored
+severity: warning
+introduced: 9.6.1
+---
+
+GHC implements the `SafeHaskell` extension which allows programmers to restrict modules to a specific subset which is considered safe and does not contain loopholes such as `unsafePerformIO`.
+More details are available in [the GHC User's Guide](https://downloads.haskell.org/ghc/latest/docs/users_guide/exts/safe_haskell.html).
+One of the features which isn't considered safe are user-specified rewrite rules. GHC therefore warns that all rewrite rules in a module which is declared safe will be ignored.