Re: [PATCH] string_list API: document what "sorted" means.

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 18, 2012, 08:19 UTC
Message-ID: <7vmx0noi8s.fsf@alter.siamese.dyndns.org>
In-Reply-To: <505829AB.8000506@alum.mit.edu>

Michael Haggerty <mhagger@alum.mit.edu> writes:

Show 16 quoted lines

> 1. Document that string_list sorts entries according to their strcmp()
> order, as proposed in this patch.  Then fetch can rely on this ordering.
>  If somebody wants a different ordering in the future, it is easy to
> make the sort order a parameter.
>
> 2. Leave string_list's "default" sort order unspecified, but already
> implement a way to let string_list users specify a particular sort
> order.  Change the fetch machinery to specify a strcmp()-based ordering
> explicitly.  This approach has the advantage of letting the default sort
> order of string_list to be changed, though I don't really see how this
> would be helpful.
>
> 3. Change fetch back to doing its own sorting again, rather than relying
> on sort_string_list().  This isn't a lot of work (inline the one line of
> sort_string_list(), then either make string-list.c:cmp_items() public or
> duplicate that function too).

I haven't looked at non-users of string-list API, but my gut feeling has been that lack of 2. made the API less useful for current non-users, possible callers that could benefit from something like string-list that lets them specify their own sort order.

Also, I actually am more worried about us wanting to change the order in which ref-list is sorted, rather than somebody randomly deciding to change the default (and only) order string-list is sorted on. When that happens, we would have even less useful string-list left behind, with a documented invariant that is not helping anybody if we choose to do 1 now.

So to me, if we really wanted to avoid doing 2 prematurely (which is a sensible concern, by the way), the more sensible option between 1 and 3 would be 3. That makes my preference 2, 3 and then 1 (but I do not care too deeply between 2 and 3).