diff --git a/docs/changelog.rst b/docs/changelog.rst
index 527806a9a..4da0bb141 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -6,6 +6,9 @@ Changelog
 
 Features:
 
+* Beets now accept top-level options ``--format-item`` and ``--format-album``
+  before any subcommand to control how items and albums are displayed.
+  :bug:`1271`:
 * There are now multiple levels of verbosity. On the command line, you can
   make beets somewhat verbose with ``-v`` or very verbose with ``-vv``.
   :bug:`1244`
@@ -120,6 +123,9 @@ Fixes:
 
 For developers:
 
+* the ``OptionParser`` is now a ``CommonOptionsParser`` that offers facilities
+  for adding usual options (``--album``, ``--path`` and ``--format``). See
+  :ref:`add_subcommands`. :bug:`1271`
 * The logging system in beets has been overhauled. Plugins now each have their
   own logger, which helps by automatically adjusting the verbosity level in
   import mode and by prefixing the plugin's name.  Logging levels are
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst
index f448b5dfa..9961ad03c 100644
--- a/docs/dev/plugins.rst
+++ b/docs/dev/plugins.rst
@@ -87,8 +87,11 @@ The function should use any of the utility functions defined in ``beets.ui``.
 Try running ``pydoc beets.ui`` to see what's available.
 
 You can add command-line options to your new command using the ``parser`` member
-of the ``Subcommand`` class, which is an ``OptionParser`` instance. Just use it
-like you would a normal ``OptionParser`` in an independent script.
+of the ``Subcommand`` class, which is a ``CommonOptionParser`` instance. Just
+use it like you would a normal ``OptionParser`` in an independent script. Note
+that it offers several methods to add common options: ``--album``, ``--path``
+and ``--format``. This feature is versatile and extensively documented, try
+``pydoc beets.ui.CommonOptionParser`` for more information.
 
 .. _plugin_events: