/brz/remove-bazaar : contents of doc/en/user-guide/bazaar

: (revision 3263)

To get this branch, use:

bzr branch
http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

2977.1.2 by Ian Clatworthy add conflict handling as an Appendix + minor tweaks	1	Workflows
	2	=========
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	3
	4	Bazaar is just a tool
	5	---------------------
	6
	7	One of the best things about Bazaar is that it supports many
	8	different ways of working together. This means that you can
	9	start with one workflow and adapt it over time as circumstances
	10	change. There is no "one true way" that always makes sense and
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	11	there never will be. This section provides a brief overview of
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	12	some popular workflows supported by Bazaar.
	13
	14
	15	Solo
	16	----
	17
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	18	Whether developing software, editing documents or changing configuration files,
	19	having an easy-to-use VCS tool can help. A single user can use this workflow
	20	effectively for managing projects where they are the only contributor.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	21
	22	.. image:: images/workflows_single.png
	23
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	24	Advantages of this workflow over not using version control at all include:
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	25
	26	* backup of old versions
	27	* rollback to an earlier state
	28	* tracking of history.
	29
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	30	The key features of Bazaar appropriate for this workflow are low administration
	31	(no server setup) and ease of use.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	32
	33
	34	Partner
	35	-------
	36
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	37	Sometimes two people need to work together sharing changes as they go. This
	38	commonly starts off as a Solo workflow (see above) or a team-oriented
	39	workflow (see below). At some point, the second person takes a branch (copy
	40	including history) of what the first person has done. They can then work in
	41	parallel exchanging changes by merging when appropriate.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	42
	43	.. image:: images/workflows_peer.png
	44
	45	Advantages over Solo are:
	46
	47	* easier sharing of changes
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	48	* each line of each text file can be attributed to a particular change
	49	including who changed it, when and why.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	50
	51	When implementing this workflow, Bazaar's advantages over CVS and Subversion include:
	52
	53	* no server to setup
	54	* intelligent merging means merging multiple times isn't painful.
	55
	56
	57	Centralized
	58	-----------
	59
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	60	Also known as lock-step, this is essentially the same as the workflow
	61	encouraged/enforced by CVS and Subversion. All developers work on the same
	62	branch (or branches). They run ``bzr update`` to get their checkout up-to-date,
	63	then ``bzr commit`` to publish their changes to the central location.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	64
	65	.. image:: images/workflows_centralized.png
	66
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	67	Subversion and CVS are good choices for implementing this workflow because they
	68	make it easy. Unlike the vast majority of distributed VCS tools, Bazaar makes
	69	it easy as well by directly supporting it. In addition, Bazaar provides some
	70	important advantages over CVS and Subversion:
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	71
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	72	* better branching and merging
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	73	* better renaming support.
	74
	75
	76	Centralized with local commits
	77	------------------------------
	78
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	79	This is essentially the same as the Centralized model, except that when
	80	developers are making a series of changes, they do ``commit --local`` or unbind
	81	their checkout. When it is complete, they commit their work to the shared
	82	mainline.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	83
	84	.. image:: images/workflows_localcommit.png
	85
	86	Advantages over Centralized:
	87
	88	* Can work offline, e.g. when disconnected during travel
	89	* Less chance for a bad commit to interfere with everyone else's work
	90
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	91	Subversion and CVS do not support this model. Other distributed VCS tools can
	92	support it but do so less directly than Bazaar does.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	93
	94
	95	Decentralized with shared mainline
	96	----------------------------------
	97
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	98	In this workflow, each developer has their own branch or branches, plus commit
	99	rights to the main branch. They do their work in their personal branch, then
	100	merge it into the mainline when it is ready.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	101
	102	.. image:: images/workflows_shared.png
	103
	104	Advantage over Centralized with local commits:
	105
	106	* Easier organization of work - separate changes can be developed in their own branches
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	107	* Developers can merge one another's personal branches when working on something together.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	108
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	109	Subversion and CVS do not support this model. Other distributed VCS
	110	tools support it. Many features of Bazaar are good for this workflow
	111	including ease of use, shared repositories, integrated merging and
	112	rich metadata (including directory rename tracking).
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	113
	114
	115	Decentralized with human gatekeeper
	116	-----------------------------------
	117
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	118	In this workflow, each developer has their own branch or branches, plus
	119	read-only access to the main branch. One developer (the gatekeeper) has commit
	120	rights to the main branch. When a developer wants their work merged, they ask
	121	the gatekeeper to merge it. The gatekeeper does code review, and merges the
	122	work into the main branch if it meets the necessary standards.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	123
	124	.. image:: images/workflows_gatekeeper.png
	125
	126	Advantage over Decentralized with shared mainline:
	127
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	128	* Code is always reviewed before it enters the mainline
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	129	* Tighter control over when changes get incorporated into the mainline.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	130
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	131	A companion tool of Bazaar's called Bundle Buggy can be very useful for
	132	tracking what changes are up for review, their status and reviewer comments.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	133
	134
	135	Decentralized with automatic gatekeeper
	136	---------------------------------------
	137
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	138	In this workflow, each developer has their own branch or branches, plus
	139	read-only access to the mainline. A software gatekeeper has commit rights to
	140	the main branch. When a developer wants their work merged, they request another
	141	person to review it. Once it has passed review, either the original author or
	142	the reviewer asks the gatekeeper software to merge it, depending on team
	143	policies. The gatekeeper software does a merge, a compile, and runs the test
	144	suite. If and only if the code passes, it is merged into the mainline.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	145
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	146	Note: As an alternative, the review step can be skipped and the author can
	147	submit the change to the automatic gatekeeper without it. (This is particularly
	148	appropriate when using practices such as Pair Programming that effectively
	149	promote just-in-time reviews instead of reviewing code as a separate step.)
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	150
	151	.. image:: images/workflows_pqm.png
	152
	153	Advantages over Decentralized with human gatekeeper:
	154
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	155	* Code is always tested before it enters the mainline (so the integrity of the
	156	mainline is higher)
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	157	* Scales better as teams grow.
	158
3237.1.2 by John Arbash Meinel wrap doc/en/user-guide/bazaar_workflows.txt for 79 characters	159	A companion tool of Bazaar's called Patch Queue Manager (PQM) can provide the
	160	automated gatekeeper capability.
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	161
	162
	163	Implementing a workflow
	164	-----------------------
	165
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	166	For an in-depth look at how to implement each of the workflows above,
2977.1.17 by Ian Clatworthy more chapter 1 tweaks	167	see chapters 3 to 6 in this manual. First though, chapter 2
2977.1.1 by Ian Clatworthy First cut at new look User Guide including chapters 1 and 2	168	explains some important pre-requisites including installation, general
	169	usage instructions and configuration tips.