Make the getting started section in the README better

Make the getting started section in the README better

Some of my colleagues have commented in the past few months that the
Breakpad README is not very clear on how to get and build the code
nowadays. This change moves some of the docs from the "request
change review" section up to the "getting started" section, and adds
a few more things to clarify.

R=vapier@chromium.org
BUG=

Committed: https://chromium.googlesource.com/breakpad/breakpad/+/8b7b28663f679c2ad71a263f7491f1eb316f667b

[vapier, 2016-06-03 14:58:36]

you can upload the CL to gerrit and verify gitiles there:

git push origin HEAD:refs/for/master

then in the gerrit page, look for the commit/gitiles link and you can spot check
the README rendering.  then when you're done, just abandon it.

you might have to insert a Change-Id field temporarily into the commit message
so you don't keep creating a new CL every time you push.

https://codereview.chromium.org/2035103002/diff/1/README.md
File README.md (right):

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode13
README.md:13: ## Getting started (from trunk)
s/trunk/master/ ?

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode16
README.md:16: 2.  Create a new directory for checking out the source code (it
must be named breakpad):
i'd prefer to use a period at the end of each of these bullet points rather than
a colon

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode27
README.md:27: 4.  Build the source:
looks like you want a blank line above this (based on the other sections)

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode35
README.md:35: This will build the processor tools on all platforms
(`src/processor/minidump_stackwalk`, `src/processor/minidump_dump`, etc), and on
Linux it will also build the client libraries and some tools
(`src/tools/linux/dump_syms/dump_syms`,
`src/tools/linux/md2core/minidump-2-core`, etc).
line wrap to 80 cols ?

the "on all platforms" is confusing.  not sure what you're going for there.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode50
README.md:50: To update an existing checkout to a newer revision, you can `git
pull origin master` as usual, but then you should run `gclient sync` to ensure
that the dependent repos are up-to-date.
line wrap to 80 cols ?

do you really need "origin master" ?  seems like `git pull` should be
sufficient.  or does gclient set up weird remotes ?

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode52
README.md:52: ## To request change review:
drop the trailing colon.  it makes the TOC look weird.

[Ted Mielczarek, 2016-06-03 16:40:40]

https://codereview.chromium.org/2035103002/diff/1/README.md
File README.md (right):

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode13
README.md:13: ## Getting started (from trunk)
On 2016/06/03 14:58:35, vapier wrote:
> s/trunk/master/ ?

Done.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode16
README.md:16: 2.  Create a new directory for checking out the source code (it
must be named breakpad):
On 2016/06/03 14:58:35, vapier wrote:
> i'd prefer to use a period at the end of each of these bullet points rather
than
> a colon

Done.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode27
README.md:27: 4.  Build the source:
On 2016/06/03 14:58:35, vapier wrote:
> looks like you want a blank line above this (based on the other sections)

Done.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode35
README.md:35: This will build the processor tools on all platforms
(`src/processor/minidump_stackwalk`, `src/processor/minidump_dump`, etc), and on
Linux it will also build the client libraries and some tools
(`src/tools/linux/dump_syms/dump_syms`,
`src/tools/linux/md2core/minidump-2-core`, etc).
On 2016/06/03 14:58:35, vapier wrote:
> line wrap to 80 cols ?

Done.

> 
> the "on all platforms" is confusing.  not sure what you're going for there.

I agree. I meant "the processor tools will always be built regardless of what
system you're building on", but I'll just drop "on all platforms", it reads
better that way.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode50
README.md:50: To update an existing checkout to a newer revision, you can `git
pull origin master` as usual, but then you should run `gclient sync` to ensure
that the dependent repos are up-to-date.
On 2016/06/03 14:58:35, vapier wrote:
> line wrap to 80 cols ?
> 
> do you really need "origin master" ?  seems like `git pull` should be
> sufficient.  or does gclient set up weird remotes ?

Done. The remotes are normal, just all the git docs I've ever read usually say
`git pull origin master`.

https://codereview.chromium.org/2035103002/diff/1/README.md#newcode52
README.md:52: ## To request change review:
On 2016/06/03 14:58:35, vapier wrote:
> drop the trailing colon.  it makes the TOC look weird.

Done.

[Ted Mielczarek, 2016-06-03 16:41:41]

On 2016/06/03 14:58:36, vapier wrote:
> you can upload the CL to gerrit and verify gitiles there:
> 
> git push origin HEAD:refs/for/master
> 
> then in the gerrit page, look for the commit/gitiles link and you can spot
check
> the README rendering.  then when you're done, just abandon it.
> 
> you might have to insert a Change-Id field temporarily into the commit message
> so you don't keep creating a new CL every time you push.
> 

Thanks, that was helpful! Here's what it looks like there:
https://chromium.googlesource.com/breakpad%2Fbreakpad/+/eab2544fd2340a3dbc5a6...

and on GitHub:
https://github.com/luser/breakpad/blob/readme-checkout/README.md

[vapier, 2016-06-03 17:21:05]

lgtm

[Ted Mielczarek, 2016-06-03 17:32:03]

Description was changed from

==========
Make the getting started section in the README better

Some of my colleagues have commented in the past few months that the
Breakpad README is not very clear on how to get and build the code
nowadays. This change moves some of the docs from the "request
change review" section up to the "getting started" section, and adds
a few more things to clarify.

Hopefully this renders nicely in Gitiles, I verified that GitHub's
markdown renderer renders it properly using grip
(https://github.com/joeyespo/grip)

R=vapier@chromium.org
BUG=
==========

to

==========
Make the getting started section in the README better

Some of my colleagues have commented in the past few months that the
Breakpad README is not very clear on how to get and build the code
nowadays. This change moves some of the docs from the "request
change review" section up to the "getting started" section, and adds
a few more things to clarify.

R=vapier@chromium.org
BUG=
==========

[Ted Mielczarek, 2016-06-03 17:32:16]

Description was changed from

==========
Make the getting started section in the README better

Some of my colleagues have commented in the past few months that the
Breakpad README is not very clear on how to get and build the code
nowadays. This change moves some of the docs from the "request
change review" section up to the "getting started" section, and adds
a few more things to clarify.

R=vapier@chromium.org
BUG=
==========

to

==========
Make the getting started section in the README better

Some of my colleagues have commented in the past few months that the
Breakpad README is not very clear on how to get and build the code
nowadays. This change moves some of the docs from the "request
change review" section up to the "getting started" section, and adds
a few more things to clarify.

R=vapier@chromium.org
BUG=

Committed:
https://chromium.googlesource.com/breakpad/breakpad/+/8b7b28663f679c2ad71a263...
==========

[Ted Mielczarek, 2016-06-03 17:32:18]

Committed patchset #3 (id:40001) manually as
8b7b28663f679c2ad71a263f7491f1eb316f667b (presubmit successful).