diff --git a/lib/builtin.pm b/lib/builtin.pm
index 0980884359b7..5d80564e0c32 100644
--- a/lib/builtin.pm
+++ b/lib/builtin.pm
@@ -1,4 +1,4 @@
-package builtin 0.015;
+package builtin 0.016;
 
 use v5.40;
 
@@ -106,6 +106,13 @@ The following bundles currently exist:
     :5.40      true false weaken unweaken is_weak blessed refaddr reftype
                ceil floor is_tainted trim indexed
 
+=head2 Function Optimisations
+
+There are a number of optimisations that apply to functions in the L<builtin>
+package.  If you replace or override these functions (such as by assignment
+into glob references) the optimisations may not take effect.  Do so with
+caution.
+
 =head1 FUNCTIONS
 
 =head2 true