[MERGE/RFC] Dotted-decimal revision numbers in 'bzr log'

[Martin Pool]

On  8 Sep 2006, Robert Collins <robertc at robertcollins.net> wrote:
> > > === modified file 'bzrlib/tests/blackbox/test_log.py'
> > > --- bzrlib/tests/blackbox/test_log.py	2006-07-28 16:05:23 +0000
> > > +++ bzrlib/tests/blackbox/test_log.py	2006-09-07 03:24:18 +0000
> > 
> > Thanks for updating the example in this comment.  It seems to me that
> > now we have assertEqualDiff we could compare the whole thing, if we just
> > pass extra parameters to the commits to set the committer, time, 
> > timezone and rev_id?  That would be nicer.
> 
> For now, I'd like to leave it - I dont think this test will gain a lot,
> and it will be more complex to do.... I really want to get the doctest
> pattern matcher into TestCase at some point which will give a good
> balance.

OK

>>> @@ -174,18 +174,29 @@
>>>                                 old revision listed in the mainline revisions
>>>                                 list.
>>>                                 The order for this parameter is oldest-first.
>>> +    :generate_revno: Optional parameter controlling the generation of revision
>>> +        number sequences in the output. See the output description of the
>>> +        MergeSorter docstrng for details.
>>>  

Incidentally should be :param generate_revno:.  I should set up an
epydoc job, and perhaps grep for people forgetting :param: because it's
so easy to do.

>>> -    The result is a list of node names, such that all parents come before
>>> -    their children.
>>> +    The result is a list sorted to that all parents come before

s//sorted so that/

>>> +    their children. Each element of the list is a tuple containing:
>>> +    (sequence_number, node_name, merge_depth, end_of_merge)
>>> +     * sequence_number: The sequence of this row in the output. Useful for 
>>> +       GUIs.
>>> +     * node_name: The node name, opaque text to the merge routine.

It'd be clearer to change the comma to a colon.

>>> +     * merge_depth: How many levels of merging deep this node has been found.
>>> +     * end_of_merge: When True the next node is part of a different merge.

> > Surely api stability implies not changing the return type?
> 
> The return type is not changed unless you pass in 'generate_revno'.
> 
> If we make the generate_revno=False version deprecated, then users will
> have a hint to change their code.

OK, but that's not what the comment says.  It says the result is always
a sequence of 4-tuples, both for merge_sort() and MergeSorter.__init__. 

If we're changing the return type maybe we should make a new routine
rather than adding a parameter to merge_sort(), at least at the public
interface level?

-- 
Martin