changeset 124:0bee8982f334

learning in workflows mostly finished - I hope :) .

--- a/text/learning_mercurial_in_workflows.txt	Tue Apr 28 13:07:25 2009 +0200
+++ b/text/learning_mercurial_in_workflows.txt	Tue Apr 28 23:21:15 2009 +0200
@@ -410,19 +410,122 @@
 
 == Collaborative feature development ==
 
--> branches 
+Now that we can share changes and reverse them if necessary, we go one step further: Using Mercurial to help in coordinating the coding. 
+
+The first part is an easy way to develop features together, without requiring every developer to keep track of several feature clones. 
+
+=== Use Case ===
+
+When you want to split your development into several features, you need to keep track of who works on which feature and where to get which changes. 
+
+Mercurial makes this easy for you by providing names branches. They are a part of the main repository, so they are available to everyone involved. At the same time, changes committed on a certain branch don't get mixed into the changes in the default branch, so features are kept seperate, until they get merged into the default branch. 
+
+=== Workflow ===
+
+When someone in your group wants to start coding on a feature without disturbing the others, he can create a named branch and commit there. When someone else wants to join in, he just updates to the branch and commits away. As soon as the feature is finished, someone merges the named branch into the default branch. 
+
+Create a named branch (name: feature1) and work on it: 
+
+$ hg branch feature1
+(do some changes)
+$ hg commit
+(write commit message)
+
+Update into the branch and work in it: 
+
+$ hg update feature1
+(do some changes)
+$ hg commit
+(write commit message)
+
+Now you can commit, pull, push and merge as if they were working in a seperate repository. If the history of the named branch is linear and you call "hg merge", Mercurial asks you to specify an explicit revision, since the branch in which you work doesn't have anything to merge. 
+
+When you finished the feature, you merge it back into the default branch. 
 
-== Tagging revisions ==
+$ hg update default
+$ hg merge feature1
+$ hg commit
+(write commit message)
+
+And that's it. Now you can easily keep features seperate without unnecessary bookkeeping. 
+
+== Marking revisions: tag and sign ==
+
+=== Use Case ===
+
+Since you can now code seperate features more easily, you might want to mark certain revisions as fit for consumption (or similar). For example you might want to mark releases, or just mark off revisions as reviewed. 
+
+For this Mercurial offers tags. Tags add a name to a revision and are part of the history. You can tag a change years after it was committed. The tag includes the information when it was added, and tags can be pulled, pushed and merged just like any other committed change. 
+
+Note: A tag must not contain the char ":", since that char is used for specifying multiple reivions - see "hg help revisions". 
 
--> hg tag
+=== Workflow ===
+
+Let's assume you want to give revision 3 the name "v0.1". 
+
+Add the tag: 
+
+$ hg tag -r 3 v0.1
+
+See all tags: 
+
+$ hg tags
+
+When you look at the log you'll now see a line in changeset 3 which marks the Tag. If someone wants to update to the tagged revision, he can just use the name of your tag: 
+
+$ hg update v0.1
+
+Now he'll be at the tagged revision and can work from there. 
+
 
 == Removing history == 
 
--> hg clone -r , hg export, hg import, ...
+=== Use Case ===
+
+At times you will have changes in your repository, which you really don't want in it. 
+
+There are many advanced options for removing these, and of them most use great extensions (Mercurial Queues is the most often used one), but in this basic guide, we'll solve the problem with just the commands we already learned. But we'll use an option to clone which we didn't yet use. 
+
+This workflow becomes inconvenient when you need to changes, which are buried below many new changes. If you spot it early enough, you can get rid of them without too much effort, though. 
+
+=== Workflow ===
+
+Let's assume you want to get rid of revision 2 and we have 3 revisions in total. 
+
+The first step is to use the "--rev" option to clone: Create a clone which only contains the changes up to the specified revision. This means that you want to keep revision 1, so we only clone up to that. 
+
+$ hg clone -r 1 project stripped
+
+Now you can export the change 3 from the original repository (project) and import it into the stripped one. 
 
+$ cd project
+$ hg export 3 > ../changes.diff
+$ cd ../stripped
+$ hg import ../changes.diff
+
+If a part of the changes couldn't be applied, you'll see that part in *.rej files. If you have *.rej files, you'll have to include or discard changes by hand. 
+
+$ cat *.rej
+(apply changes by hand)
+$ hg commit
+(write commit message)
+
+That's it. "hg export" also includes the commit message, date, committer and similar metadata, so you are already done. 
+
+Note: removing history will change the revision IDs of revisions after the removed one, and if you pull from someone else who still has the revision you removed, you will pull the removed parts again. That's why rewriting history should most times only be done for changes which you didn't yet publicise. 
+
+== Summary ==
+
+So now you can work with Mercurial in private, and also share your changes in a multitude of ways. 
+
+Additionally to that you can also remove bad changes, either by creating a change in the repository which reverses the original change, or by really rewriting history, so it looks like the change never occured. 
+
+And you can seperate the work on features in a single repository by using named branches and add tags to revisions which are visible markers for others and can be used to update to the tagged revisions. 
+
+With this we can conclude our practical guide. 
 
 = More Complex Workflows =
 
-
+If you now want to check some more compelx workflows, please have a look at the general [workflows](workflows) page. 
 
-= Smoothing workflows with extensions =
\ No newline at end of file
+Have fun with Mercurial! 
\ No newline at end of file