Enhance documentation about FUTURE build option

Jay Berkenbilt
1 parent 4101596f
Showing 3 changed files with 17 additions and 2 deletions
manual/installation.rst
manual/packaging.rst
manual/release-notes.rst
@@ -279,8 +279,13 @@ BUILD_SHARED_LIBS, BUILD_STATIC_LIBS
  
 FUTURE
   This option enables changes planned for the next major release to be
-  included. These changes are ABI breaking and are subject to change. They
-  are NOT part of the stable API.
+  included. They are NOT part of the stable API. These changes are ABI
+  breaking and are subject to change, which means code linked against
+  a qpdf built with this option may not be binary compatible with
+  installed qpdf libraries. Set this if you want to test your code
+  with proposed QPDF API changes and provide feedback prior to the
+  inclusion of those changes in a release. Packagers should never
+  distribute backages built with this option.
  
 QTEST_COLOR
   Turn this on or off to control whether qtest uses color in its
@@ -26,6 +26,12 @@ particularly useful to packagers.
   combined with either ``ctest --verbose`` or ``ctest
   --output-on-failure``.
  
+- Packagers should never define the ``FUTURE`` build option. API
+  changes enabled by ``FUTURE`` are not stable and may be
+  API/ABI-breaking. That option is intended only for people who are
+  testing their code with a local build of qpdf to provide early
+  feedback or prepare for possible future changes to the API.
+
 - qpdf's install targets do not install completion files by default
   since there is no standard location for them. As a packager, it's
   good if you install them wherever your distribution expects such
@@ -6,6 +6,10 @@ Release Notes
 For a detailed list of changes, please see the file
 :file:`ChangeLog` in the source distribution.
  
+If you are a developer and want to test your code against future API
+changes that are under consideration, you can build qpdf locally and
+enable the ``FUTURE`` build option (see :ref:`build-options`).
+
 Planned changes for future 12.x (subject to change):
   - ``QPDFObjectHandle`` will support move construction/assignment.
     This change will be invisible to most developers but may break