Changes between Version 9 and Version 10 of BazaarWorkflow

Timestamp:

2009-08-17T18:43:21Z (15 years ago)

Author:

Jiri Svoboda

Comment:

NOW it should make some sense… hopefully.

BazaarWorkflow

@@ -5 +5 @@
 == Linear History ==
 
-If you are doing a simple change (or several simple, unrelated changes) you might try to go for linear history. This will only work if nobody else pushed any changes to the main repository while you were doing your changes. Start by creating your private branch:
+If you are doing a simple change (or several simple, unrelated changes) you might try to go for linear history. But remember that you will actually not be taking advantage of the distributed VCS, instead using it as a centralized tool.
+
+Remember that this will only work if nobody else pushed any changes to the main repository while you were doing your changes. Start by creating your private branch:
 
 {{{
@@ -43 +45 @@
 == Structured History ==
 
-Stuctured history is '''good'''. If you are working on some feature and produce several related commits, it is better to group them to a separate branch. Also, with Bazaar it is not uncommon to have long-running branches (that are merged after weeks, months). Do not be afraid of structured history.
+Stuctured history is '''good''' and merging is the most natural operation in a distributed VCS. If you are working on some feature and produce several related commits, it is better to group them to a separate branch. Even better, you can have one (or more) private branches that you keep all the time. Do not be afraid of structured history.
 
-If your branch diverged from the mainline (i.e. somebody pushed to the main repository since you branched off), you cannot push anymore. You must merge the two branches. With merging, the order of arguments is significant. You must always ''merge your branch into the mainline'', never the other way around! How can you do this? With bazaar you can only merge to a local repository (you need to chdir into it), you cannot merge to a remote repository.
+=== Merging Into the Mainline ===
+
+Let us say your branch diverged from the mainline (i.e. somebody pushed to the main repository since you branched off). This is perfectly normal. You can work on your branch independently of the mainline. However, from time to time you might want to actually propagate your great new changes to the mainline. We do it by merging.
+
+With merging, the order of arguments is significant. You must always ''merge your branch into the mainline'', never the other way around! How can you do this? With bazaar you can only merge to a local repository (you need to chdir into it), you cannot merge to a remote repository.
 
 Therefore we have to resort to a little trick. Suppose your branch {{{my_branch}}} diverged from the mainline. We thus create a new branch {{{head_clone}}} which will be a clone of the mainline:
@@ -67 +73 @@
 }}}
 
-Finally let us sync our branch with the main repository:
+=== Keeping Your Branch Up to Date ===
+
+From time to time you might want to add the latest changes from mainline into your private branch. You do this simply by merging from the mainline:
 
 {{{
-head_clone$ cd ../my_branch
-my_branch$ bzr pull
+my_branch$ bzr merge bzr://bzr.helenos.org/head my_branch
+my_branch$ bzr commit -m "Merge latest mainline changes."
 }}}
 
-Again, the push might have failed if somebody else pushed since you created your {{{head_clone}}}. In that case probably the best idea is to try and rebase your merge commit to the new mainline head.
+== What if I pull from mainline to my feature branch? ==
+
+The effect is that the mainline head will become the head of your repository. Consequently, your repository will not continue your feature branch, but it will branch off a new branch from the mainline. If you do {{{bzr log}}} it will show the mainline's history beyond the new branching point, not the history of your feature branch.
+
+Working this way will result in creating lots of short feature branches which start and finish. If you merge from the mainline instead, you will get one long branch.
+
+== What would happen if I pushed from my feature branch to the mainline? ==
+
+The main repository would inherit the head of your feature branch as its head. Your feature branch would become the mainline and the repository's history will become confused. If you did this, well, '''shame on you'''! However, it can still be fixed to some extent by creating a new merge changeset which would merge the offending head into the mainline. (I.e., the right way around.) You should rather ask someone competent to do this. In any case it will produce some confusing changesets in the history.
 
 == Conclusion ==
 
-Unfortunately we have no way of enforcing the right direction of merges. So think twice before you push.
+We are still trying to determine whether it is possible to check for bad merges automatically. So please be careful what you push into the main repository. If you are unsure, ask for help.