~bzr-pqm/bzr/bzr.dev : contents of doc/en/user-guide/organizing

~bzr-pqm/bzr/bzr.dev : (revision 5718.9.2)

Organizing branches
===================

Mirror branches
---------------

A primary difference when using distributed workflows to
develop is that your main local branch is not the place
to make changes. Instead, it is kept as a pristine copy
of the central branch, i.e. it's a *mirror branch*.

To create a mirror branch, set-up a shared repository
(if you haven't already) and then use the ``branch``
(or ``checkout``) command to create the mirror.
For example::

  bzr init-repo PROJECT
  cd PROJECT
  bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk

Task branches
-------------

Each new feature or fix is developed in its own branch.
These branches are referred to as *feature branches* or
*task branches* - the terms are used interchangeably.

To create a task branch, use the ``branch`` command
against your mirror branch. For example::

  bzr branch trunk fix-123
  cd fix-123
  (hack, hack, hack)

There are numerous advantages to this approach:

 1. You can work on multiple changes in parallel
 2. There is reduced coupling between changes
 3. Multiple people can work in a peer-to-peer mode
    on a branch until it is ready to go.

In particular, some changes take longer to cook than others
so you can ask for reviews, apply feedback, ask for another
review, etc. By completing work to sufficient quality in
separate branches before merging into a central branch, the
quality and stability of the central branch are maintained
at higher level than they otherwise would be.

Refreshing a mirror branch
--------------------------

Use the ``pull`` command to do this::

  cd trunk
  bzr pull

Merging the latest trunk into a feature branch
----------------------------------------------

Use the ``merge`` command to do this::

  cd fix-123
  bzr merge
  (resolve any conflicts)
  bzr commit -m "merged trunk"

Merging a feature into the trunk
--------------------------------

The policies for different distributed workflows vary here.
The simple case where all developers have commit rights to
the main trunk are shown below.

If your mirror is a checkout::

  cd trunk
  bzr update
  bzr merge ../fix-123
  (resolve any conflicts)
  bzr commit -m "Fixed bug #123"

If your mirror is a branch::

  cd trunk
  bzr pull
  bzr merge ../fix-123
  (resolve any conflicts)
  bzr commit -m "Fixed bug #123"
  bzr push

Backing up task branches
------------------------

One of the side effects of centralized workflows is that changes
get frequently committed to a central location which is backed up as
part of normal IT operations. When developing on task branches,
it is a good idea to publish your work to a central location
(but not necessarily a shared location) that will be backed up.
You may even wish to bind local task branches to remote ones
established on a backup server just for this purpose.

2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	1	Organizing branches
	2	===================
	3
	4	Mirror branches
	5	---------------
	6
	7	A primary difference when using distributed workflows to
	8	develop is that your main local branch is not the place
	9	to make changes. Instead, it is kept as a pristine copy
	10	of the central branch, i.e. it's a mirror branch.
	11
	12	To create a mirror branch, set-up a shared repository
	13	(if you haven't already) and then use the ``branch``
	14	(or ``checkout``) command to create the mirror.
	15	For example::
	16
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	17	bzr init-repo PROJECT
	18	cd PROJECT
5761.1.1 by Martin Pool Recommend SSH rather than SFTP in user documentation examples	19	bzr branch bzr+ssh://centralhost/srv/bzr/PROJECT/trunk
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	20
	21	Task branches
	22	-------------
	23
	24	Each new feature or fix is developed in its own branch.
3535.2.1 by Viktor Nagy corrected some typos	25	These branches are referred to as feature branches or
4011.6.1 by Frank Aspell Fixed typos.	26	task branches - the terms are used interchangeably.
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	27
	28	To create a task branch, use the ``branch`` command
	29	against your mirror branch. For example::
	30
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	31	bzr branch trunk fix-123
	32	cd fix-123
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	33	(hack, hack, hack)
	34
	35	There are numerous advantages to this approach:
	36
	37	1. You can work on multiple changes in parallel
	38	2. There is reduced coupling between changes
	39	3. Multiple people can work in a peer-to-peer mode
	40	on a branch until it is ready to go.
	41
	42	In particular, some changes take longer to cook than others
	43	so you can ask for reviews, apply feedback, ask for another
	44	review, etc. By completing work to sufficient quality in
	45	separate branches before merging into a central branch, the
	46	quality and stability of the central branch are maintained
	47	at higher level than they otherwise would be.
	48
	49	Refreshing a mirror branch
	50	--------------------------
	51
	52	Use the ``pull`` command to do this::
	53
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	54	cd trunk
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	55	bzr pull
	56
	57	Merging the latest trunk into a feature branch
	58	----------------------------------------------
	59
	60	Use the ``merge`` command to do this::
	61
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	62	cd fix-123
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	63	bzr merge
	64	(resolve any conflicts)
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	65	bzr commit -m "merged trunk"
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	66
	67	Merging a feature into the trunk
	68	--------------------------------
	69
	70	The policies for different distributed workflows vary here.
	71	The simple case where all developers have commit rights to
	72	the main trunk are shown below.
	73
	74	If your mirror is a checkout::
	75
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	76	cd trunk
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	77	bzr update
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	78	bzr merge ../fix-123
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	79	(resolve any conflicts)
	80	bzr commit -m "Fixed bug #123"
	81
	82	If your mirror is a branch::
	83
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	84	cd trunk
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	85	bzr pull
3918.1.1 by Jari Aalto In user guide, use 'PROJECT' as a metavariable not 'X-repo'	86	bzr merge ../fix-123
2977.1.10 by Ian Clatworthy 2nd cut at Distributed collaboration chapter	87	(resolve any conflicts)
	88	bzr commit -m "Fixed bug #123"
	89	bzr push
	90
	91	Backing up task branches
	92	------------------------
	93
	94	One of the side effects of centralized workflows is that changes
	95	get frequently committed to a central location which is backed up as
	96	part of normal IT operations. When developing on task branches,
	97	it is a good idea to publish your work to a central location
	98	(but not necessarily a shared location) that will be backed up.
	99	You may even wish to bind local task branches to remote ones
	100	established on a backup server just for this purpose.