Update CHANGELOG; Improve refinements.md

Author: ssnickolay

CHANGELOG.md

@@ -56,9 +56,10 @@ Compatibility:
 * Implemented `rb_enc_isalnum` and `rb_enc_isspace`.
 * `RUBY_REVISION` is now the full commit hash used to build TruffleRuby, similar to MRI 2.7+.
 * Implemented `rb_enc_mbc_to_codepoint`.
-* Change the lookup methods to achieve Refinements specification (#2033, @ssnickolay)
+* Changed the lookup methods to achieve Refinements specification (#2033, @ssnickolay)
 * Implemented `Digest::Instance#new` (#2040).
 * Implemented `ONIGENC_MBC_CASE_FOLD`.
+* Fixed `refine + super` compatibility (#2039, @ssnickolay)
 
 Performance:
 

doc/contributor/refinements.md

@@ -88,12 +88,15 @@ The lookup order:
 R1 -> A -> B -> R2 -> D -> E -> C -> ...
 ```
 
-The `super` lookup works in much the same way, except `C` ancestors have a higher priority than other active refinements.
+## Super Dispatch
 
-The lookup order for `super`:
-```ruby
-R1 -> A -> B -> C -> ... -> R2 -> D -> E -> C -> ...
-```
+
+The `super` lookup [works in two modes](https://bugs.ruby-lang.org/issues/16977):
+
+1. If `super` is called from a method is directly in R, then we should search in `C` ancestors and ignore other active refinements.
+2. If `super` is called from a method placed in a module which included to R, then we should search overall active refinements (as we do for a regular lookup).
+
+Additionally, `super` has access to the caller active refinements, so we use `InterlaMethod#activeRefinements` to keep and re-use necessary refinements.
 
 ## References