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

"Michael S. Tsirkin" <mst@redhat.com> writes:

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.