Document .subst-mutate will be deprecated in future

Originally planned[^1] to be deprecated in 6.d for reasons[^1], but due to R#1289 [^2]
we're postponing it for later language versions.
[^1] https://github.com/perl6/6.d-prep/blob/master/TODO/FEATURES.md#deprecate-strsubst-mutate
[^2] rakudo/rakudo#1289

Author: zoffixznet

doc/Type/Str.pod6

@@ -862,9 +862,7 @@ Returns the invocant string where C<$matcher> is replaced by C<$replacement>
 
 There is an in-place syntactic variant of C<subst> spelled
 L«C<s/matcher/replacement/>|/syntax/s$SOLIDUS%20$SOLIDUS%20$SOLIDUS» and with
-adverb following the C<s> or inside the matcher,  as well as the
-L«C<.subst-mutate> method|/routine/subst-mutate» which modifies the string
-in-place.
+adverb following the C<s> or inside the matcher.
 
 C<$matcher> can be a L<Regex>, or a literal C<Str>. Non-Str matcher arguments
 of type L<Cool> are coerced to C<Str> for literal matching.
@@ -948,6 +946,11 @@ The C<:nth> adverb has readable English-looking variants:
 
 =head2 method subst-mutate
 
+B<NOTE:> I<<< C<.subst-mutate> will be deprecated in future language
+versions. You can use L<subst> with
+L«C<.=> method call assignment operator|/routine/.=.html» or
+L«C<s///> substitution operator|/syntax/s$SOLIDUS$SOLIDUS$SOLIDUS» instead. >>>
+
 Where L<subst> returns the modified string and leaves the original
 unchanged, it is possible to mutate the original string by using
 C<subst-mutate>. If the match is successful, the method returns a L<Match>