From bc137b174fee0266cd8c19cfb43bc9fb518787e8 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Wed, 2 Sep 2015 15:05:23 -0700
Subject: [PATCH] Doc tweaks & changelog for #1589

---
 beets/mediafile.py | 24 +++++++++++++++---------
 docs/changelog.rst |  3 +++
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/beets/mediafile.py b/beets/mediafile.py
index e82b14aae..64ab49ac2 100644
--- a/beets/mediafile.py
+++ b/beets/mediafile.py
@@ -1461,11 +1461,14 @@ class MediaFile(object):
                 yield property.decode('utf8')
 
     @classmethod
-    def field_sort_name(cls, name):
-        """Get field name for sorting purposes. Fields names are kept
-        unchanged, unless they are instances of :class:`DateItemField`,
-        in which case `year`, `month`, and `day` are replaced by `date0`,
-        `date1`, and `date2`, respectively.
+    def _field_sort_name(cls, name):
+        """Get a sort key for a field name that determines the order
+        fields should be written in.
+
+        Fields names are kept unchanged, unless they are instances of
+        :class:`DateItemField`, in which case `year`, `month`, and `day`
+        are replaced by `date0`, `date1`, and `date2`, respectively, to
+        make them appear in that order.
         """
         if isinstance(cls.__dict__[name], DateItemField):
             name = re.sub('year',  'date0', name)
@@ -1475,11 +1478,14 @@ class MediaFile(object):
 
     @classmethod
     def sorted_fields(cls):
-        """Get the names of all writable metadata fields sorted by
-        lexicographic order (except for instances of :class:`DateItemField`,
-        which are sorted in year-month-day order).
+        """Get the names of all writable metadata fields, sorted in the
+        order that they should be written.
+
+        This is a lexicographic order, except for instances of
+        :class:`DateItemField`, which are sorted in year-month-day
+        order.
         """
-        for property in sorted(cls.fields(), key=cls.field_sort_name):
+        for property in sorted(cls.fields(), key=cls._field_sort_name):
             yield property
 
     @classmethod
diff --git a/docs/changelog.rst b/docs/changelog.rst
index 0e09d3303..3148119b1 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -33,6 +33,9 @@ Fixes:
 * :doc:`/plugins/fetchart`: The plugin now fetches PNGs but not GIFs. (It
   still fetches JPEGs.) This avoids an error when trying to embed images,
   since not all formats support GIFs. :bug:`1588`
+* Date fields are now written in the correct order (year-month-day), which
+  eliminates an intermittent bug where the latter two fields would not get
+  written to files. Thanks to :user:`jdetrey`. :bug:`1303` :bug:`1589`
 
 
 1.3.14 (August 2, 2015)