Re: [PATCH v5 5/9] patch-id: document new behaviour

["Michael S. Tsirkin" <mst@redhat.com>]

On Thu, Apr 24, 2014 at 03:12:14PM -0700, Junio C Hamano wrote:
> "Michael S. Tsirkin" <mst@redhat.com> writes:
> 
> >> > +--unstable::
> >> > +	Use a non-symmetrical sum of hashes, such that reordering
> >> 
> >> What is a non-symmetrical sum?
> >
> > Non-symmetrical combination function is better?
> 
> I do not think either is very good X-<.
> 
> The primary points to convey for "--stable" are:
> 
>  - Two patches produced by comparing the same two trees with two
>    different settings for "-O<orderfile>" will result in the same
>    patchc signature, thereby allowing the computed result to be used
>    as a key to index some metainformation about the change between
>    the two trees;
> 
>  - It will produce a result different from the plain vanilla
>    patch-id has always produced even when used on a diff output
>    taken without any use of "-O<orderfile>", thereby making existing
>    databases keyed by patch-ids unusable.
> 
> The fact that we happened to use a patch-id that catches that
> somebody reordered the same patch into different file order and
> declares that they are two different changes is a more historical
> accident than a designed goal.
> 
> I would even say that we would have used the "stable" version from
> the beginning if we thought that "-O<orderfile>" would be widely
> used when these two features both appeared.  Even though I was the
> guilty one who introduced it, I'd admit that "-O<orderfile>" has
> merely been a curiosity from its inception and has been a failed
> experiment, not in the sense that the feature does not work as
> adverertised (it does), but in the sense that it is not widely used
> (evidenced by the lack of complaints on missing diff.orderfile for a
> long time) at all.  With "-O<orderfile>" being a failed experiment,
> the "unstability" did not matter, so it has stuck.
> 
> The only two things worth mentioning about "--unstable", if our
> future direction is to see diff.orderfile and "--stable" a lot more
> widely used, are:
> 
>  (1) it keeps producing the same patch-id as existing versions of
>      Git, so users with existing databases (who do not deal with
>      reordered patches) may want to use it; and perhaps
> 
>  (2) it will not consider a patch taken with "-O<orderfile>" and
>      another without it from the same source the same patches.
> 
> Mathmatically speaking, mentioning "non-symmetrial" might be one way
> of expressing the latter point (2), but stressing on that alone
> without mentioning (1) misses the point.  (2) is _not_ a designed
> feature, so it is not very interesting.  Unless you have an existing
> database, there is no reason to use "--unstable".
> 
> On the other hand (1) is a very relevant thing to mention, as we are
> talking about a feature that, if unused, may break existing users'
> data.

OK I did just that, pls take a look.