Merge pull request #693 from sivaraam/master

Few changes to the "Distributed Workflow" chapter

Author: ben

book/05-distributed-git/sections/contributing.asc

@@ -20,7 +20,7 @@ Are all the patches peer-reviewed and approved?
 Are you involved in that process?
 Is a lieutenant system in place, and do you have to submit your work to them first?
 
-The next issue is your commit access.
+The next variable is your commit access.
 The workflow required in order to contribute to a project is much different if you have write access to the project than if you don't.
 If you don't have write access, how does the project prefer to accept contributed work?
 Does it even have a policy?
@@ -61,7 +61,7 @@ The Git project requires that the more detailed explanation include your motivat
 It's also a good idea to use the imperative present tense in these messages.
 In other words, use commands.
 Instead of ``I added tests for'' or ``Adding tests for,'' use ``Add tests for.''
-Here is a template originally written by Tim Pope:
+Here is a http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[template originally written by Tim Pope]:
 
 [source,text]
 ----
@@ -87,7 +87,7 @@ Further paragraphs come after blank lines.
 If all your commit messages look like this, things will be a lot easier for you and the developers you work with.
 The Git project has well-formatted commit messages – try running `git log --no-merges` there to see what a nicely formatted project-commit history looks like.
 
-In the following examples, and throughout most of this book, for the sake of brevity this book doesn't have nicely-formatted messages like this; instead, we use the `-m` option to `git commit`.
+For the sake of brevity, the following examples, and most examples in other parts of this book,  don't have nicely-formatted messages like this; instead, we use the `-m` option to `git commit`.
 Do as we say, not as we do.
 
 [[_private_team]]
@@ -177,7 +177,7 @@ John has a reference to the changes Jessica pushed up, but he has to merge them
 [source,console]
 ----
 $ git merge origin/master
-Merge made by recursive.
+Merge made by the 'recursive' strategy.
  TODO |    1 +
  1 files changed, 1 insertions(+), 0 deletions(-)
 ----
@@ -276,7 +276,7 @@ Now Jessica merges in John's work (`origin/master`):
 ----
 $ git merge origin/master
 Auto-merging lib/simplegit.rb
-Merge made by recursive.
+Merge made by the 'recursive' strategy.
  lib/simplegit.rb |    2 +-
  1 files changed, 1 insertions(+), 1 deletions(-)
 ----
@@ -394,7 +394,7 @@ Jessica can now merge this into the work she did with `git merge`:
 ----
 $ git merge origin/featureBee
 Auto-merging lib/simplegit.rb
-Merge made by recursive.
+Merge made by the 'recursive' strategy.
  lib/simplegit.rb |    4 ++++
  1 files changed, 4 insertions(+), 0 deletions(-)
 ----
@@ -520,8 +520,8 @@ $ git remote add myfork (url)
 
 Then you need to push your work up to it.
 It's easiest to push the topic branch you're working on up to your repository, rather than merging into your master branch and pushing that up.
-The reason is that if the work isn't accepted or is cherry picked, you don't have to rewind your master branch.
-If the maintainers merge, rebase, or cherry-pick your work, you'll eventually get it back via pulling from their repository anyhow:
+The reason is that if the work isn't accepted or is cherry-picked, you don't have to rewind your master branch.
+If the maintainers `merge`, `rebase`, or `cherry-pick` your work, you'll eventually get it back via pulling from their repository anyhow:
 
 [source,console]
 ----
@@ -566,6 +566,7 @@ $ git checkout -b featureB origin/master
 # (work)
 $ git commit
 $ git push myfork featureB
+$ git request-pull origin/master myfork
 # (email maintainer)
 $ git fetch origin
 ----

book/05-distributed-git/sections/distributed-workflows.asc

@@ -66,13 +66,13 @@ This is a variant of a multiple-repository workflow.
 It's generally used by huge projects with hundreds of collaborators; one famous example is the Linux kernel.
 Various integration managers are in charge of certain parts of the repository; they're called lieutenants.
 All the lieutenants have one integration manager known as the benevolent dictator.
-The benevolent dictator's repository serves as the reference repository from which all the collaborators need to pull.
+The benevolent dictator pushes from his directory to a reference repository from which all the collaborators need to pull.
 The process works like this (see <<wfdiag_c>>):
 
 1.  Regular developers work on their topic branch and rebase their work on top of `master`.
-    The `master` branch is that of the dictator.
+    The `master` branch is that of the reference directory to which the dictator pushes.
 2.  Lieutenants merge the developers' topic branches into their `master` branch.
-3.  The dictator merges the lieutenants' `master` branches into the dictator's `master` branch.
+3.  The dictator merges the lieutenants' `master` branches into their `master` branch.
 4.  The dictator pushes their `master` to the reference repository so the other developers can rebase on it.
 
 [[wfdiag_c]]

book/05-distributed-git/sections/maintaining.asc

@@ -163,8 +163,8 @@ Falling back to patching base and 3-way merge...
 No changes -- Patch already applied.
 ----
 
-In this case, this patch had already been applied.
-Without the `-3` option, it looks like a conflict.
+In this case, without the `-3` option the patch would have been considered as a conflict.
+Since the `-3` option was used the patch applied cleanly.
 
 If you're applying a number of patches from an mbox, you can also run the `am` command in interactive mode, which stops at each patch it finds and asks if you want to apply it:
 
@@ -197,7 +197,7 @@ $ git fetch jessica
 $ git checkout -b rubyclient jessica/ruby-client
 ----
 
-If she emails you again later with another branch containing another great feature, you can fetch and check out because you already have the remote setup.
+If she emails you again later with another branch containing another great feature, you could directly `fetch` and `checkout` because you already have the remote setup.
 
 This is most useful if you're working with a person consistently.
 If someone only has a single patch to contribute once in a while, then accepting it over email may be less time consuming than requiring everyone to run their own server and having to continually add and remove remotes to get a few patches.
@@ -215,7 +215,7 @@ This does a one-time pull and doesn't save the URL as a remote reference:
 $ git pull https://github.com/onetimeguy/project
 From https://github.com/onetimeguy/project
  * branch            HEAD       -> FETCH_HEAD
-Merge made by recursive.
+Merge made by the 'recursive' strategy.
 ----
 
 [[_what_is_introduced]]
@@ -297,7 +297,7 @@ You have a number of choices, so we'll cover a few of them.
 ===== Merging Workflows
 
 (((workflows, merging)))
-One simple workflow merges your work into your `master` branch.
+One simple workflow is to merge the work into your `master` branch.
 In this scenario, you have a `master` branch that contains basically stable code.
 When you have work in a topic branch that you've done or that someone has contributed and you've verified, you merge it into your master branch, delete the topic branch, and then continue the process.
 If we have a repository with work in two branches named `ruby_client` and `php_client` that looks like <<merwf_a>> and merge `ruby_client` first and then `php_client` next, then your history will end up looking like <<merwf_b>>.
@@ -329,9 +329,9 @@ image::images/merging-workflows-4.png[After a topic branch merge.]
 .After a project release.
 image::images/merging-workflows-5.png[After a topic branch release.]
 
-This way, when people clone your project's repository, they can either check out master to build the latest stable version and keep up to date on that easily, or they can check out develop, which is the more cutting-edge stuff.
-You can also continue this concept, having an integrate branch where all the work is merged together.
-Then, when the codebase on that branch is stable and passes tests, you merge it into a develop branch; and when that has proven itself stable for a while, you fast-forward your master branch.
+This way, when people clone your project's repository, they can either check out `master` to build the latest stable version and keep up to date on that easily, or they can check out `develop`, which is the more cutting-edge stuff.
+You can also extend this concept by having an `integrate` branch where all the work is merged together.
+Then, when the codebase on that branch is stable and passes tests, you merge it into a `develop` branch; and when that has proven itself stable for a while, you fast-forward your `master` branch.
 
 ===== Large-Merging Workflows
 
@@ -357,7 +357,7 @@ The Git project also has a `maint` branch that is forked off from the last relea
 Thus, when you clone the Git repository, you have four branches that you can check out to evaluate the project in different stages of development, depending on how cutting edge you want to be or how you want to contribute; and the maintainer has a structured workflow to help them vet new contributions.
 
 [[_rebase_cherry_pick]]
-===== Rebasing and Cherry Picking Workflows
+===== Rebasing and Cherry-Picking Workflows
 
 (((workflows, rebasing and cherry-picking)))
 Other maintainers prefer to rebase or cherry-pick contributed work on top of their master branch, rather than merging it in, to keep a mostly linear history.