view docs/evolve-good-practice.rst @ 6364:e8d85d51c7b2 stable

topic: monkey-patch ctx.branch() correctly in override_context_branch

There's a `for p in ctx.parents()` loop in this block of code, and it's used to
monkey-patch .branch() method for both parents of ctx. It assigns each parent
of ctx to variable `p` (implicitly) and p.branch method to variable `pbranch`
(explicitly).

This worked fine when there's only one p1, but when there were 2 parents, this
code was broken, and our tests didn't catch this because the use of
override_context_branch context manager is quite limited.

The problem is that the newly created function uses `p` and `pbranch`, and the
closures for the new p1.branch() and p2.branch() didn't get created until the
for-loop finished, and the values `p` and `pbranch` could change before that.
In other words, the new .branch method of p1 was effectively identical to p2's
because the values that were available to it were from the second cycle of the
for-loop, when it the loop was at p2.

Now we pass the values to a function that creates the new .branch methods, and
since these values are provided to overridebranch() as arguments, they get
enclosed when the function returns.

This was seen (and tested) during topic namespaces-related work, when
override_context_branch usage was expanded to include some local operations.

.. Copyright 2011 Pierre-Yves David <[e-mail]>
..                Logilab SA        <[e-mail]>

-----------------------------------------
Good practice for (early) users of evolve
-----------------------------------------

Avoid unstability
-----------------

The less unstability you have the less you need to resolve.

Evolve is not yet able to detect and solve every situation. And your mind is
not ready neither.

Branch as much as possible
--------------------------

This is not MQ; you are not constrained to linear history.

Making a branch per independent branch will help you avoid unstability
and conflict.

Rewrite your changes only
-------------------------

There is no descent conflict detection and handling right now.
Rewriting other people's changesets guarantees that you will get
conflicts. Communicate with your fellow developers before trying to
touch other people's work (which is a good practice in any case).

Using multiple branches will help you to achieve this goal.

Prefer pushing unstability to touching other people changesets
--------------------------------------------------------------


If you have children changesets from other people that you don't really care
about, prefer not altering them to risking a conflict by stabilizing them.


Do not get too confident
------------------------

This is an experimental extension and a complex concept. This is beautiful,
powerful and robust on paper, but the tool and your mind may not be prepared for
all situations yet.