Merge lp://staging/~nmb/bzr/fix-481526 into lp://staging/bzr

This branch adds a brief discussion of using --force to create merge revisions with more than two parents, as requested in bug 481526

25 + revision which merges two other branches, say ``../feature1a`` and
26 + ``../feature1b``::

You can't use ReST syntax here since the docstring is displayed as is :)

28 + $ bzr merge ../feature1a
29 + # working tree has changes so need --force
30 + $ bzr merge ../feature1b --force
31 + # resolve conflicts, test, etc.
32 + $ bzr commit -m 'revision with three parents'

The other examples in this docstring don't use the '$' and '#' prefixes,
I suspect that's ReST striking again. I suggest deleting the '$' prefix
and just use normal sentences for the comments and move that part in the
'Examples' section.

Changed formatting in the branch, please re-review.

Thanks !

Your NEWS entry is still not sorted, to avoid conflicts we sort
NEWS entries inside each section.
Since this bug (and #505093 too) is related to documentation it should even
go into the 'Documentation' section.

In the following tweak, 'Add' comes before 'Improve' which comes
before 'Improved':

=== modified file 'NEWS'
--- NEWS 2010-01-18 22:05:00 +0000
+++ NEWS 2010-01-21 09:02:54 +0000
@@ -111,12 +111,6 @@
   should appear up-to-date.)
   (John Arbash Meinel, Martin <gzlist>, #488724)

-* Improve discussion of pending merges in the documentation for
- ``revert``. (Neil Martinsen-Burrell, #505093)
-
-* Add documentation on creating merges with more than one parent.
- (Neil Martinsen-Burrell, #481526)
-
 Improvements
 ************

@@ -143,6 +137,12 @@
 Documentation
 *************

+* Add documentation on creating merges with more than one parent.
+ (Neil Martinsen-Burrell, #481526)
+
+* Improve discussion of pending merges in the documentation for
+ ``revert``. (Neil Martinsen-Burrell, #505093)
+
 * Improved help for ``bzr send``.
   (Martin Pool, Bojan Nikolic)

I'll tweak and merge.

Is that sorted lexicographically? Should I be merging bzr.dev frequently to my branches in order to get the up to date NEWS entries so that I can sort mine into the list correctly? Is this documented in HACKING.txt? I understand that NEWS conflicts are a big pain and I'd like to make my patches merge as smoothly as possible, but I'm not sure precisely how I should be doing that.

My interpretation of what HACKING.txt says is that bug fixes belong in the Bug Fixes section. I'd be fine leaving these sorts of tweaks out of NEWS entirely, but it has been mentioned on the ML that putting even small bug fixes in NEWS is good for perception.

>>>>> "Neil" == Neil Martinsen-Burrell <email address hidden> writes:

    Neil> Is that sorted lexicographically?

Yes.

    Neil> Should I be merging bzr.dev frequently to my branches
    Neil> in order to get the up to date NEWS entries so that I
    Neil> can sort mine into the list correctly?

When I start working on a bug, I generally do:

  bzr branch lp:bzr <bug number>-<short-bug-description>

So I always have a pretty decent NEWS file. The later you start
your branch, the less conflicts you can encounter.

If you want to target the stable release, you start with
lp:bzr/2.0 instead of lp:bzr and since that's a stable branch,
you're less likely to have conflicts :)

    Neil> Is this documented in HACKING.txt?

I honestly can't remember.

    Neil> I understand that NEWS conflicts are a big pain and I'd
    Neil> like to make my patches merge as smoothly as possible,
    Neil> but I'm not sure precisely how I should be doing that.

Not a *big* pain, but when no tweaks at all are required, I can
pqm-submit directly from your branch instead of creating a local
one.

    Neil> My interpretation of what HACKING.txt says is that bug fixes
    Neil> belong in the Bug Fixes section.

Sure, but we also have a 'Documentation' section and we encourage
people to file bugs with the 'doc' tag.

    Neil> I'd be fine leaving these sorts of tweaks out of NEWS
    Neil> entirely, but it has been mentioned on the ML that
    Neil> putting even small bug fixes in NEWS is good for
    Neil> perception.

I think it *is* good to add them.

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Vincent Ladeuil wrote:
>>>>>> "Neil" == Neil Martinsen-Burrell <email address hidden> writes:
>
> Neil> Is that sorted lexicographically?
>
> Yes.
>
> Neil> Should I be merging bzr.dev frequently to my branches
> Neil> in order to get the up to date NEWS entries so that I
> Neil> can sort mine into the list correctly?
>
> When I start working on a bug, I generally do:
>
> bzr branch lp:bzr <bug number>-<short-bug-description>
>
> So I always have a pretty decent NEWS file. The later you start
> your branch, the less conflicts you can encounter.
>
> If you want to target the stable release, you start with
> lp:bzr/2.0 instead of lp:bzr and since that's a stable branch,
> you're less likely to have conflicts :)
>
> Neil> Is this documented in HACKING.txt?
>
> I honestly can't remember.
>
> Neil> I understand that NEWS conflicts are a big pain and I'd
> Neil> like to make my patches merge as smoothly as possible,
> Neil> but I'm not sure precisely how I should be doing that.
>
> Not a *big* pain, but when no tweaks at all are required, I can
> pqm-submit directly from your branch instead of creating a local
> one.
>

Of course, if we set up PQM to use the new 'news_merge' plugin, we
shouldn't even have to worry about it then, right?

I've set it up locally, though one concern is that I won't know when it
is triggering. I guess I should notice fewer conflicts, at least.

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAktYiisACgkQJdeBCYSNAAOjHQCdFrtef1eTa5kGhpwAyB3qbzx+
6Y4An0UDtkvP91n8GpTEpVkLFlNbwsvz
=+e4h
-----END PGP SIGNATURE-----

John A Meinel wrote:
[...]
> Of course, if we set up PQM to use the new 'news_merge' plugin, we
> shouldn't even have to worry about it then, right?

In many cases. It's pretty simple; read its docs to see the
limitations. I expect it to always do at least as well as 3-way merge.
So at least spurious conflicts that only occur due to sorting clashes
within a section will be avoided.

It probably could do better with 2.0 -> trunk merges, AFAIK we always
want to duplicate NEWS entries to the 2.0.X section and to the current
2.1rcX section, but news_merge isn't yet smart enough to do that.

> I've set it up locally, though one concern is that I won't know when it
> is triggering. I guess I should notice fewer conflicts, at least.

Yeah. I guess having an option to make it noisier would be good.

-Andrew.

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Andrew Bennetts wrote:
> John A Meinel wrote:
> [...]
>> Of course, if we set up PQM to use the new 'news_merge' plugin, we
>> shouldn't even have to worry about it then, right?
>
> In many cases. It's pretty simple; read its docs to see the
> limitations. I expect it to always do at least as well as 3-way merge.
> So at least spurious conflicts that only occur due to sorting clashes
> within a section will be avoided.
>
> It probably could do better with 2.0 -> trunk merges, AFAIK we always
> want to duplicate NEWS entries to the 2.0.X section and to the current
> 2.1rcX section, but news_merge isn't yet smart enough to do that.

I reversed that policy when I started releasing them in sync. (The
argument was that if they release at different times, then we need to
know what was in which.) For the last few releases I've been removing
the duplicates.

A concern is for the "cleanup a typo" sort of conflict. If I clean up a
typo in a block, and you get a merge conflict including that block, will
you end up with 2 copies of the logically same block, along with your
new block. For example:

* My foob

then

* My foob

* New Bar

and

* My foo

(AIUI, These won't directly conflict, because of the blank line, but I
think we could force something.)

When merging these, a conflict is better than getting

* My foo

* My foob

* New Bar

>
>> I've set it up locally, though one concern is that I won't know when it
>> is triggering. I guess I should notice fewer conflicts, at least.
>
> Yeah. I guess having an option to make it noisier would be good.
>
> -Andrew.
>

John
=:->
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAktej4wACgkQJdeBCYSNAAOuJwCgjiN71htvH6tv1qqC78YBl+tq
TgkAnRXVY3bmgxbl9LUfSZq2uQT63/Vp
=6F8Q
-----END PGP SIGNATURE-----

2010/1/21 Vincent Ladeuil <email address hidden>:
>>>>>> "Neil" == Neil Martinsen-Burrell <email address hidden> writes:
>
>    Neil> Is that sorted lexicographically?
>
> Yes.
>
>    Neil> Should I be merging bzr.dev frequently to my branches
>    Neil> in order to get the up to date NEWS entries so that I
>    Neil> can sort mine into the list correctly?
>
> When I start working on a bug, I generally do:
>
>  bzr branch lp:bzr <bug number>-<short-bug-description>
>
> So I always have a pretty decent NEWS file. The later you start
> your branch, the less conflicts you can encounter.
>
> If you want to target the stable release, you start with
> lp:bzr/2.0 instead of lp:bzr and since that's a stable branch,
> you're less likely to have conflicts :)
>
>    Neil> Is this documented in HACKING.txt?
>
> I honestly can't remember.

If it's not, it would be nice if you could summarize this into there
somewhere. It's always good to improve the documentation at the
moment you learn the undocumented thing.

>
>    Neil> I understand that NEWS conflicts are a big pain and I'd
>    Neil> like to make my patches merge as smoothly as possible,
>    Neil> but I'm not sure precisely how I should be doing that.
>
> Not a *big* pain, but when no tweaks at all are required, I can
> pqm-submit directly from your branch instead of creating a local
> one.

I wouldn't worry too much about it up to the moment the merge is sent to pqm.

>    Neil> My interpretation of what HACKING.txt says is that bug fixes
>    Neil> belong in the Bug Fixes section.
>
> Sure, but we also have a 'Documentation' section and we encourage
> people to file bugs with the 'doc' tag.

Right, 'bug fixes' is more for actual code 'defect' as opposed to doc
or enhancements, even though we might track them in
bugs.launchpad.net.
>    Neil> I'd be fine leaving these sorts of tweaks out of NEWS
>    Neil> entirely, but it has been mentioned on the ML that
>    Neil> putting even small bug fixes in NEWS is good for
>    Neil> perception.
>
> I think it *is* good to add them.

I think it is, for a few reasons, with the perception of lots getting
done not being the most important:

* we can look over the news to get an overview of what changed
* it gives credit to people who do work in a more visible way than the
commit logs
* it's a fast way to find out when something changed if for instance
you're trying to tell a user what they have to upgrade to to get a
particular fix
* it gives people an idea of things to test or read

That said there is a lower bound; I fixed a broken link in the docs
and didn't add news for that. This one is probably getting close to
that limit.

Also you can combine multiple commits into one news entry, to just say
"better help for merge, foo, bar, ...."

--
Martin <http://launchpad.net/~mbp/>

John A Meinel wrote:
[...]
> A concern is for the "cleanup a typo" sort of conflict. If I clean up a
> typo in a block, and you get a merge conflict including that block, will
> you end up with 2 copies of the logically same block, along with your
> new block. For example:
>
> * My foob
>
> then
>
> * My foob
>
> * New Bar
>
> and
>
> * My foo
>
> (AIUI, These won't directly conflict, because of the blank line, but I
> think we could force something.)

Try it; one side will calculate:

  * added New Bar

The other will calculate:

  * deleted My foob
  * added My foo

And so the combination is:

  * My foo
  * New Bar

So, I think it handles this case.

-Andrew.