From 3336b68d08429e9efd0dd74bc28053c3e6228173 Mon Sep 17 00:00:00 2001
From: henry <137741507+henry-oberholtzer@users.noreply.github.com>
Date: Thu, 18 Sep 2025 02:33:55 -0700
Subject: [PATCH] Fix musicbrainz plugin documentation (#6024)

Add several lines to documentation to clear up possible confusion on
musicbrainz plugin being disabled when plugin list is modified.

closes #6020
---
 docs/changelog.rst     |  7 +++++++
 docs/faq.rst           |  4 +++-
 docs/guides/tagger.rst | 10 ++++++++++
 docs/plugins/index.rst |  6 +++---
 4 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/docs/changelog.rst b/docs/changelog.rst
index 9a514f9f0..4dc38da94 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -15,6 +15,13 @@ For packagers:
 
 Other changes:
 
+- :doc:`plugins/index`: Clarify that musicbrainz must be mentioned if plugin
+  list modified :bug:`6020`
+- :doc:`/faq`: Add check for musicbrainz plugin if auto-tagger can't find a
+  match :bug:`6020`
+- :doc:`guides/tagger`: Section on no matching release found, related to
+  possibly disabled musicbrainz plugin :bug:`6020`
+
 2.4.0 (September 13, 2025)
 --------------------------
 
diff --git a/docs/faq.rst b/docs/faq.rst
index 718356e42..3e527e8bc 100644
--- a/docs/faq.rst
+++ b/docs/faq.rst
@@ -236,7 +236,9 @@ Why does beets…
 
 There are a number of possibilities:
 
-- First, make sure the album is in `the MusicBrainz database
+- First, make sure you have at least one autotagger extension/plugin enabled.
+  See :ref:`autotagger_extensions` for a list of valid plugins.
+- Check that the album is in `the MusicBrainz database
   <https://musicbrainz.org/>`__. You can search on their site to make sure it's
   cataloged there. (If not, anyone can edit MusicBrainz---so consider adding the
   data yourself.)
diff --git a/docs/guides/tagger.rst b/docs/guides/tagger.rst
index 3ad85ec85..c07d5df58 100644
--- a/docs/guides/tagger.rst
+++ b/docs/guides/tagger.rst
@@ -289,11 +289,21 @@ MusicBrainz---so consider adding the data yourself.
 
 .. _the musicbrainz database: https://musicbrainz.org/
 
+If you receive a "No matching release found" message from the Auto-Tagger for an
+album you know is present in MusicBrainz, check that musicbrainz is in the
+plugin list. Until version v2.4.0_ the default metadata source for the
+Auto-Tagger, the :doc:`musicbrainz plugin </plugins/musicbrainz>`, had to be
+manually disabled. At present, if the plugin list is changed, musicbrainz needs
+to be added to the plugin list in order to continue contributing results to
+Auto-Tagger.
+
 If you think beets is ignoring an album that's listed in MusicBrainz, please
 `file a bug report`_.
 
 .. _file a bug report: https://github.com/beetbox/beets/issues
 
+.. _v2.4.0: https://github.com/beetbox/beets/releases/tag/v2.4.0
+
 I Hope That Makes Sense
 -----------------------
 
diff --git a/docs/plugins/index.rst b/docs/plugins/index.rst
index 960ecfbef..64874dd32 100644
--- a/docs/plugins/index.rst
+++ b/docs/plugins/index.rst
@@ -18,7 +18,7 @@ list), just use the ``plugins`` option in your :doc:`config.yaml
 
 .. code-block:: sh
 
-    plugins: inline convert web
+    plugins: musicbrainz inline convert web
 
 The value for ``plugins`` can be a space-separated list of plugin names or a
 YAML list like ``[foo, bar]``. You can see which plugins are currently enabled
@@ -29,7 +29,7 @@ its name:
 
 .. code-block:: yaml
 
-    plugins: inline convert web
+    plugins: musicbrainz inline convert web
 
     convert:
         auto: true
@@ -58,7 +58,7 @@ following to your configuration:
 
 .. code-block:: yaml
 
-    plugins: discogs
+    plugins: musicbrainz discogs
 
     discogs:
        source_weight: 0.0