[Monotone-devel] Re: monotone disapprove does not give correct branch cert

[Wim Oudshoorn]

Zbynek Winkler <address@hidden> writes:

> What would be the "clear and consistent model" this time? I also like
> clear and consistent models but I think this time it is not as
> clear... IMHO clear and consistent model could be if each branch had
> exactly one branch point (one revision in each branch would be the
> *first* revision) and all revisions in the said branch would be
> descendants of this revision (thus the branches would not have holes).
>
Oh not for me :-)
>
> The only model I see now in branches is that "branch is a set of
> revisions sharing a branch certificate". I miss the single origin and
> the continuity :(

That is just my mental model and it is working perfectly.

Below I will outline my mental model of what monotone does
or should do.  Keep in mind that this is JUST my mental model
and monotone might do things differently.  I will still talk
as if monotone works the way I expect, so take it with
a grain of salt ;-)

Oh people who know monotone might skip this and jump to the
end where I continue my nitpicking rant.

MENTAL MODEL
------------

(1) The revisions are a simple direct acyclic graph.  Not 
    necessary connected.  

    That is:

        * You have revisions, which are nodes in a graph.
          A revision correspond to a collection files/directories
          with a certain content. However the content
          does NOT uniquely identify a revision.

        * You have arrows between revisions.  
          Such that there is at most one arrow
          between two revisions, and you can not
          return to you'r starting point when 
          you walk the arrows.


(2) Now on these revisions you add some extra data, the 
    certificates.  These certificates are not fundamental
    for the working of monotone.

Now the the combination with version control for me is the following:


(A) The branch label (or certificate) is used to group revisions together,
    in some conceptual group of versions (revisions).  This group
    has some identity that stays the same over time.  
    Namely it is a version of the software product you are developing.
    
    Note: This label is JUST a convenience label, to make
    the monotone user interface easy to use.

(B) The edges/arrows between the revisions I use to indicate that
    one version/revision of the software supercedes another revision.

    so  Rev 1 ---> Rev 2

    means I think Rev 2 is better than Rev 1, that is the only thing
    it does.

One important thing I want to stress here is the fact that for
me 'branch' and 'arrow' (being better) are not related at all, they
are orthogonal properties.

So I can easily have:

   Rev 1     ---->  Rev 2 
   branch A         branch B

And I still think Rev 2 is better than Rev 1, although the are 
in different branches.

 EXAMPLE
   I decided to have my source files for version 1.2.9 of my project 
   XYZ grouped together under the branch name "XYZ-1.2.9"
   and the source files for version 1.3.4 of my project 
   XYZ grouped together under the branch name "XYZ-1.3.4"

   Than it is is perfectly possible I have four versions of 
   source:


      Rev 1             ----->     Rev 2
      XYZ-1.2.9                    XYZ-1.2.9
                    \
                     \---->   Rev 3
      Rev 4                   XYZ-1.3.4
      XYZ-1.3.4
    

  With this I make the following statements:

  Rev 2 is better than Rev 1
  Rev 3 is better than Rev 1
   
  And I can ask monotone the following questions:

  - What is the best version of XYZ-1.2.9
    
    monotone update/checkout --branch=XYZ-1.2.9

    and it will answer: Rev 2

  - What is the best version of XYZ-1.3.4
    
    monotone update/checkout --branch=XYZ-1.3.4

    and it will answer:  Huh, don't know, could be Rev 3 or Rev 4.
    (actually it will complain about multiple heads)

  END EXAMPLE


Now with grouping most people have experience, it is what
we do all the time:
   
* These files are my sources for XYZ
* These files are my sources for ABC
* These files are my sources for ABC with experimental feature QQ

so these are prime candidate for branches.  Just to reiterate, 
it is not needed to make them branches, however why would you
want to fight the nice classification system monotone has?
  
The more interesting question, where do you want to put arrows?
As stated above, arrows just tell monotone which version you 
prefer.   And instead of you telling monotone explicitly which version
is better, monotone makes an educated guess:

* If you started working on Rev 1 and after a few
  changes store the new version in monotone as Rev 2.

  Monotone knows you started with one and will assume
  that all your hard work was an improvement on Rev 1,
  you would not deliberately make it worse would you?

  so it will happily add an arrow:

  Rev 1 ---> Rev 2.

* Suppose you end up in the situation that you have 
  two revisions Rev 1 and Rev 2.  And like them both, 
  so you want to combine all the good of Rev 1 with Rev 2.
  
  How do you do that?

  Well that is where monotone merge/propagate is for.
  merge/propagate does two things:

  * It will help you combine the sources from Rev 1 and Rev 2
    to create a new set of sources Rev 3.  So we have

    Rev 1
                  Rev 3
    Rev 2

  * It will mark Rev 3 a superior to Rev 1 and Rev 2, so it     
    will add the following arrows:

    Rev 1 ----->
                 Rev 3
    Rev 2 ----->


NITPICKING RANT
---------------

I see the whole monotone graph as a expression of what 
I think are good revisions, the revisions I care about.

So for my personally I like maximal freedom of how
I arrange my monotone graph, and I want the graph
to be as explicit as possible.  So with propagate
I prefer always a new node to be added.

Example:

        Rev 1          Rev 2   
        branch A  ---> branch B 

Now propagate B A
the current behavior is:

        Rev 1          Rev 2
        branch A  ---> branch B
                       branch A

Which completely loses the meaning that propagate has for me.

       Rev 1       --------->  Rev 3
       branch A                branch A
                 \        /
                   Rev 2   
                   branch B

captures the meaning a lot better.  Because Rev 3 has
two incoming edges you know it comes from a merge/propagate!


Furthermore, sometimes it would be nice to have an
empty commit because of the arbitrary meta data you can attach:            

    Rev 1        
    branch A      
    test failed  

After fixing the test, because it was a bug in the tests I want:

   Rev 1                     Rev 2
   branch A        ---->     branch A
   test failed               test succeeded


In this case the arrow more or less indicates that:
Rev 2 is better than Rev 1 because it's meta data is more accurate.
I you make the case that if meta data is an important part of your
revision you should include in the revision and don't use meta data,
I would tend to agree.  However, things like test results are only
know AFTER a revision exists, so it can not be included in the revision.
     

Hm, this e-mail is a lot longer than I anticipated, next time I will
try to be short and clear :-)

Wim Oudshoorn.