Merge lp:~nacc/launchpad/document-getpublishedsources-sort into lp:launchpad

[Nish Aravamudan]

Document the implicit sort of Archive.getPublishedSources so it does not accidentally change in the future.

As discussed on IRC with cjwatson, document the implicit sort of getPublishedSources so it does not accidentally change in the future.

[Colin Watson (cjwatson)]

review: Approve

=== modified file 'lib/lp/soyuz/interfaces/archive.py'
--- lib/lp/soyuz/interfaces/archive.py	2017-04-25 11:35:03 +0000
+++ lib/lp/soyuz/interfaces/archive.py	2017-06-22 19:15:41 +0000
@@ -502,7 +502,10 @@
             title=_("Order by creation date"),
             description=_("Return newest results first. This is recommended "
                           "for applications that need to catch up with "
-                          "publications since their last run."),
+                          "publications since their last run. If not "
+                          "specified, results are ordered by source "
+                          "package name (lexicographically), then by "
+                          "descending version and then descending ID.",
             required=False),
         )
     # Really returns ISourcePackagePublishingHistory, see below for
@@ -541,6 +544,9 @@
         :param order_by_date: Order publications by descending creation date
             and then by descending ID.  This is suitable for applications
             that need to catch up with publications since their last run.
+            If not specified, publications are ordered by source
+            package name (lexicographically), then by descending version
+            and then descending ID.
 
         :return: SelectResults containing `ISourcePackagePublishingHistory`,
             ordered by name. If there are multiple results for the same