Document issues with 'use-package's ':custom' and byte compilation

* doc/misc/use-package.texi (User options): Warn against
byte-compiling init files that use ':custom'.  (Bug#73609)

(cherry picked from commit b1be0f2ba6b05b7644080638ae26e619cbeac75c)

diff --git a/doc/misc/use-package.texi b/doc/misc/use-package.texi
index da3deb081d97727debc2e1a8916faa5c7399eafd..0ac0341fdc7b17e8d00a2b100797459328003712 100644 (file)
--- a/doc/misc/use-package.texi
+++ b/doc/misc/use-package.texi
@@ -1416,6 +1416,13 @@ for the same variable, as this risks having conflicting values in your
 use-package declaration and your @code{custom-file}, which can lead to
 problems that are both tricky and tedious to debug.
 
+Also note that if you use @code{:custom} in a file that you
+byte-compile, you could have some unexpected results if you later load
+or @code{require} @file{use-package} (e.g., due to lazy loading): the
+value of the corresponding user options could be reset back to their
+initial values.  We therefore recommend against byte-compiling files
+that use @file{use-package} with @code{:custom} settings.
+
 @node Faces
 @section Faces
 @cindex faces, setting