Add a basic tutorial for the tools in depot_tools.

Add a tutorial / walkthrough for pure-git workflow.

TBR=agable@chromium.org, szager@chromium.org
BUG=261743
Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=263164

[iannucci, 2014-04-04 17:24:28]

On 2014/04/04 08:45:32, iannucci wrote:

PTAL. The relevant changes are in `docs/src/depot_tools_tutorial.txt`

[iannucci, 2014-04-04 18:55:24]

+cmp if interested (relevant text in docs/src/depot_tools_tutorial.txt)

[agable, 2014-04-04 23:18:58]

nit below. Also, don't reference "I" -- the author of the doc should be
invisible. Also, maybe dial back the sarcasm a tad.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
File docs/src/depot_tools_tutorial.txt (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:198: This will take the diff of your branch
against it's upstream (`origin/master`),
its

[iannucci, 2014-04-04 23:22:04]

On 2014/04/04 23:18:58, agable wrote:
> nit below. Also, don't reference "I" -- the author of the doc should be
> invisible. Also, maybe dial back the sarcasm a tad.
> 

I'll nuke the 'I's, missed those. I'm not sure which sarcasm you're referring to
but I'll look over it again :(

>
https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
> File docs/src/depot_tools_tutorial.txt (right):
> 
>
https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
> docs/src/depot_tools_tutorial.txt:198: This will take the diff of your branch
> against it's upstream (`origin/master`),
> its

[agable, 2014-04-04 23:34:11]

Threw some more specific comments in. Sorry I'm sucking all the humor out of the
doc -- I just don't want a simple tutorial that I desperately rely on to get
anything done laughing at me because I don't find this all easy.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
File docs/src/depot_tools_tutorial.txt (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:14: Chromium codebase expertly.  This tutorial
explains how to do development on
nit: two spaces? Really?

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:215: a couple other nice things :). See
linkgit:git-rebase-update[1] for the full
ditch smiley

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:226: Sometimes you're pretty certain that
you've committed a certain branch, but `git
This is a poorly constructed sentence: "Sometimes, but, and." Refactor.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:306: Another useful tool is
linkgit:git-rename-branch[1]. No, I'm not going to
dry humor

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:317: Now that you know how to manage
<<_managing_multiple_cls,'independent' CLs>>,
No need to reference previous section.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:324: this time with a (not very surprising)
twist. First, `git checkout` the branch
with a twist? Really?

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:345: it, or even based 'another' branch off of
that one. Or say that you have two
"Or say that you..." is a bad construction; it does not parallel the previous
sentence.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:346: independent CLs that would actually be
much better off as dependent CLs. Not to
"Not to worry..." -> "This can be fixed by..." or something.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:353: Well that wraps up the whirlwind tour of
the 'depot_tools' helper tools. If you
This paragraph is too cute. You're a teacher, not a tour guide.

[Ryan Tseng, 2014-04-05 00:51:20]

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
File docs/src/depot_tools_tutorial.txt (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:38: * link:http://git-scm.com/book[Pro Git
book] - Pretty good overview of git to
While a good resource, I wouldn't list it as the first link for a reader with
"little to moderate attention span".

I think a good "Pre-req" is:
* Read chapter 1 and 2 of the pro git book
* Lab 01 - 09 off gitimmersion.com
* (Optional) Intro sequence #1, #2, #4 of learnGitBranching

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:142: [white]**$ fetch blink**     # Chromium
code with blink checked out to tip-of-tree
Blink (is a proper noun)

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:213: This command will update all of your CLs
to contain the latest code from their
'Like "svn update", this command will....'

If we want to draw analogies to svn, might as well go all the way and state
their closest equivalence

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:220: git. `git rebase-update` will try to
rebase all your branches for you, but if it
"Rebase" isn't really in my vocabulary when i was new to git.  From SVN, "update
all your branches for you" seems more intuitive.

Of course if you assume git knowledge, just saying "This command will fetch and
then rebase all of your branches for you" will make sense and be sufficient.

https://codereview.chromium.org/225433003/diff/1/docs/src/make_docs.sh
File docs/src/make_docs.sh (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/make_docs.sh#newcod...
docs/src/make_docs.sh:159: # Exclude files beginning with _ from the target
list. This is useful to have
80 char

[iannucci, 2014-04-05 01:31:13]

PTAL

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
File docs/src/depot_tools_tutorial.txt (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:14: Chromium codebase expertly.  This tutorial
explains how to do development on
On 2014/04/04 23:34:12, agable wrote:
> nit: two spaces? Really?

Picky picky...

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:38: * link:http://git-scm.com/book[Pro Git
book] - Pretty good overview of git to
On 2014/04/05 00:51:20, Ryan T. wrote:
> While a good resource, I wouldn't list it as the first link for a reader with
> "little to moderate attention span".
> 
> I think a good "Pre-req" is:
> * Read chapter 1 and 2 of the pro git book
> * Lab 01 - 09 off http://gitimmersion.com
> * (Optional) Intro sequence #1, #2, #4 of learnGitBranching

I restructured this section a bit. PTAL.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:142: [white]**$ fetch blink**     # Chromium
code with blink checked out to tip-of-tree
On 2014/04/05 00:51:20, Ryan T. wrote:
> Blink (is a proper noun)

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:198: This will take the diff of your branch
against it's upstream (`origin/master`),
On 2014/04/04 23:18:58, agable wrote:
> its

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:213: This command will update all of your CLs
to contain the latest code from their
On 2014/04/05 00:51:20, Ryan T. wrote:
> 'Like "svn update", this command will....'
> 
> If we want to draw analogies to svn, might as well go all the way and state
> their closest equivalence

Erg, I'd rather not. I'm not really doing that anywhere else in the tutorial
(except mentioning it once in the paragraph below).

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:215: a couple other nice things :). See
linkgit:git-rebase-update[1] for the full
On 2014/04/04 23:34:12, agable wrote:
> ditch smiley

:(

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:220: git. `git rebase-update` will try to
rebase all your branches for you, but if it
On 2014/04/05 00:51:20, Ryan T. wrote:
> "Rebase" isn't really in my vocabulary when i was new to git.  From SVN,
"update
> all your branches for you" seems more intuitive.

They'll have to learn what rebasing is. Is the previous paragraph not enough of
a hand-wave summary?

> 
> Of course if you assume git knowledge, just saying "This command will fetch
and
> then rebase all of your branches for you" will make sense and be sufficient.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:226: Sometimes you're pretty certain that
you've committed a certain branch, but `git
On 2014/04/04 23:34:12, agable wrote:
> This is a poorly constructed sentence: "Sometimes, but, and." Refactor.

PTAL

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:306: Another useful tool is
linkgit:git-rename-branch[1]. No, I'm not going to
On 2014/04/04 23:34:12, agable wrote:
> dry humor

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:317: Now that you know how to manage
<<_managing_multiple_cls,'independent' CLs>>,
On 2014/04/04 23:34:12, agable wrote:
> No need to reference previous section.

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:324: this time with a (not very surprising)
twist. First, `git checkout` the branch
On 2014/04/04 23:34:12, agable wrote:
> with a twist? Really?

*sigh*

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:345: it, or even based 'another' branch off of
that one. Or say that you have two
On 2014/04/04 23:34:12, agable wrote:
> "Or say that you..." is a bad construction; it does not parallel the previous
> sentence.

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:346: independent CLs that would actually be
much better off as dependent CLs. Not to
On 2014/04/04 23:34:12, agable wrote:
> "Not to worry..." -> "This can be fixed by..." or something.

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/depot_tools_tutoria...
docs/src/depot_tools_tutorial.txt:353: Well that wraps up the whirlwind tour of
the 'depot_tools' helper tools. If you
On 2014/04/04 23:34:12, agable wrote:
> This paragraph is too cute. You're a teacher, not a tour guide.

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/make_docs.sh
File docs/src/make_docs.sh (right):

https://codereview.chromium.org/225433003/diff/1/docs/src/make_docs.sh#newcod...
docs/src/make_docs.sh:159: # Exclude files beginning with _ from the target
list. This is useful to have
On 2014/04/05 00:51:20, Ryan T. wrote:
> 80 char

Done.

https://codereview.chromium.org/225433003/diff/1/docs/src/make_docs.sh#newcod...
docs/src/make_docs.sh:159: # Exclude files beginning with _ from the target
list. This is useful to have
On 2014/04/05 00:51:20, Ryan T. wrote:
> 80 char

Done.

[iannucci, 2014-04-11 04:41:10]

I'm landing this as-is, and I'll request feedback from you all on the rendered
content. It's hard to do in rietveld.

[iannucci, 2014-04-11 04:46:16]

The CQ bit was checked by iannucci@chromium.org

[commit-bot: I haz the power, 2014-04-11 04:46:20]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/iannucci@chromium.org/225433003/80001

[commit-bot: I haz the power, 2014-04-11 04:48:08]

The CQ bit was unchecked by commit-bot@chromium.org

[commit-bot: I haz the power, 2014-04-11 04:48:08]

Presubmit check for 225433003-80001 failed and returned exit status 1.

Running presubmit commit checks ...
Checking out rietveld...
Running save-description-on-failure.sh
Running push-basic.sh
Running upstream.sh
Running submit-from-new-dir.sh
Running abandon.sh
Running submodule-merge-test.sh
Running upload-local-tracking-branch.sh
Running hooks.sh
Running post-dcommit-hook-test.sh
Running upload-stale.sh
Running patch.sh
Running basic.sh

** Presubmit Messages **
--tbr was specified, skipping OWNERS check

** Presubmit ERRORS **
Pylint (95 files) (28.56s) failed
************* Module
/b/infra_internal/commit_queue/workdir/tools/depot_tools/docs/src/filter_demo_output.py
C0301: 82,0: Line too long (85/80)


Presubmit checks took 94.1s to calculate.

[iannucci, 2014-04-11 04:49:34]

The CQ bit was checked by iannucci@chromium.org

[commit-bot: I haz the power, 2014-04-11 04:49:38]

CQ is trying da patch. Follow status at
https://chromium-status.appspot.com/cq/iannucci@chromium.org/225433003/100001

[commit-bot: I haz the power, 2014-04-11 04:51:51]

Change committed as 263164