[net] Convert bug triage documents to Markdown.

[net] Convert bug triage documents to Markdown.

R=rdsmith
BUG=none

Committed: https://crrev.com/ddd5dc25fc2b409c7cb5654ee6ea69e10f4d58c6
Cr-Commit-Position: refs/heads/master@{#321574}

[asanka, 2015-03-17 16:15:51]

asanka@chromium.org changed reviewers:
+ rdsmith@chromium.org

[asanka, 2015-03-17 16:15:51]

asanka@chromium.org changed required reviewers:
+ rdsmith@chromium.org

[asanka, 2015-03-17 16:18:51]

Staging at http://a.cam:8080/src/+/docs-in-markdown/net/docs/bug-triage.md

Things to look for:
* Formatting for readability. Should be glance friendly for folks to use as a
quick reference. I'm not sure we are quite there yet.

* Links are linkified and correct.

I'd like to avoid changes to the prose if we can avoid it in this patch so that
it's primarily a formatting change. Although I've had to change a couple of
headings during the conversion.

[Randy Smith (Not in Mondays), 2015-03-17 19:49:58]

Thanks very much!  A couple of top level thoughts:
* Obviously, Matt needs to be at least aware of this and maybe sign off on it
before it goes in.  You might want to see if he's good with this direction
before you put too much work in; if he has some reason for really not wanting
MD, no point in wasting time.
* The HTML ends up all the way at the left edge of the browser window, which is
a bit uncomfortable for reading.  I don't know if we want to do anything about
that.
* If extra blank lines can be put in the markdown without messing up the
readability of the HTML (which I don't think they can be :-J), that would
improve MD readability.  
* I've made a couple other comments about MD readability and linkification, but
we may be doing a tradeoff on that.  Personally, I think it's worth it; if I'm
not actually editing the doc, I'm very likely to be working off the HTML.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-labels.md
File net/docs/bug-triage-labels.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-labels....
net/docs/bug-triage-labels.md:21: https://proxy.googlezip.net:443, with
compress.googlezip.net:80 as a
This shows the proxy url as an actual link in the HTML, which I'm not sure is
what we want?

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
File net/docs/bug-triage-suggested-workflow.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:30: * The backtrace.  Note that the
backtrace should not be added to the bug if
The attempt to indent fails here and works below starting at "Clicking on the
signature", FWIW.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:53:
https://code.google.com/p/chromium/issues/list?can=2&q=status%3Aunconfirmed&s...
For HTML readability, you might not want to have this visible as a full URL
(though making it a link is useful).  That means that the triager can't directly
edit the URL before using it, but if you describe in the text what the URL is,
maybe that's good enough?

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:55: * Press `h` to bring up a preview
of the bug text.
There's a big gap after this in the HTML, for some reason I can't understand.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:82:
https://code.google.com/p/chromium/issues/list?can=2&q=Cr%3DInternals-Network...
Same comment; for the HTML, I'd put these into links and let folks use "copy
link address" if they want the URL.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:117:
https://sites.google.com/a/chromium.org/dev/for-testers/providing-network-det....
Same comment; -> link.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md
File net/docs/bug-triage.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md#newc...
net/docs/bug-triage.md:12: * Request data about recent `Cr-Internals-Network`
issue.
nit, suggestion: I'm not sure what to do about this, but every line in the HTML
that has something in quotes like this results in spacing glitches between that
line and the next one, which catches the eye as you read the HTML.   Any
thoughts about how to deal with this?  We could just leave the labels unquoted.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md#newc...
net/docs/bug-triage.md:47: * Mark it as `WontFix` (working as intended, obsolete
issue) or a duplicate.
This doesn't result in an indented list in the HTML.  I'm not sure why, but it
does work in the SDCH docs, so there's something off in the markdown.

[asanka, 2015-03-17 20:36:30]

asanka@chromium.org changed reviewers:
+ mmenke@chromium.org

[asanka, 2015-03-17 22:23:14]

+mmenke

Changes in this patchset:

* Added some whitespace for readability of the .md files. As a side-effect, that
added whitespace to the HTML. I'm okay with it.

* Removed backticks. Gitiles Markdown exporter seems to mess up the formatting
when they are there.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-labels.md
File net/docs/bug-triage-labels.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-labels....
net/docs/bug-triage-labels.md:21: https://proxy.googlezip.net:443, with
compress.googlezip.net:80 as a
On 2015/03/17 19:49:57, rdsmith wrote:
> This shows the proxy url as an actual link in the HTML, which I'm not sure is
> what we want?

Unlinkified.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
File net/docs/bug-triage-suggested-workflow.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:30: * The backtrace.  Note that the
backtrace should not be added to the bug if
On 2015/03/17 19:49:57, rdsmith wrote:
> The attempt to indent fails here and works below starting at "Clicking on the
> signature", FWIW.

Fixed.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:53:
https://code.google.com/p/chromium/issues/list?can=2&q=status%3Aunconfirmed&s...
On 2015/03/17 19:49:57, rdsmith wrote:
> For HTML readability, you might not want to have this visible as a full URL
> (though making it a link is useful).  That means that the triager can't
directly
> edit the URL before using it, but if you describe in the text what the URL is,
> maybe that's good enough?

Added a description. Let me know if we should describe the query.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:55: * Press `h` to bring up a preview
of the bug text.
On 2015/03/17 19:49:57, rdsmith wrote:
> There's a big gap after this in the HTML, for some reason I can't understand.

Yeah. It was because of the formatting for the link. Should be okay now.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:82:
https://code.google.com/p/chromium/issues/list?can=2&q=Cr%3DInternals-Network...
On 2015/03/17 19:49:57, rdsmith wrote:
> Same comment; for the HTML, I'd put these into links and let folks use "copy
> link address" if they want the URL.

Done.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage-suggest...
net/docs/bug-triage-suggested-workflow.md:117:
https://sites.google.com/a/chromium.org/dev/for-testers/providing-network-det....
On 2015/03/17 19:49:57, rdsmith wrote:
> Same comment; -> link.

Done.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md
File net/docs/bug-triage.md (right):

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md#newc...
net/docs/bug-triage.md:12: * Request data about recent `Cr-Internals-Network`
issue.
On 2015/03/17 19:49:57, rdsmith wrote:
> nit, suggestion: I'm not sure what to do about this, but every line in the
HTML
> that has something in quotes like this results in spacing glitches between
that
> line and the next one, which catches the eye as you read the HTML.   Any
> thoughts about how to deal with this?  We could just leave the labels
unquoted.

Yeah. I removed the backticks.

https://codereview.chromium.org/1017743002/diff/1/net/docs/bug-triage.md#newc...
net/docs/bug-triage.md:47: * Mark it as `WontFix` (working as intended, obsolete
issue) or a duplicate.
On 2015/03/17 19:49:57, rdsmith wrote:
> This doesn't result in an indented list in the HTML.  I'm not sure why, but it
> does work in the SDCH docs, so there's something off in the markdown.

Added another level of indentation. That seems to have done it.

I also added numbers to "procedural" instructions.

[asanka, 2015-03-17 22:24:41]

mmenke: http://a.cam:8080/src/+/docs-in-markdown/net/docs/bug-triage.md has the
staged version of the latest patchset, if you would like to see what the
rendered Markdown looks like.

[Randy Smith (Not in Mondays), 2015-03-18 16:25:59]

LGTM with issue below (but I do consider that issue important, so do please
confirm after you fix it that it stays fixed :-}; there's clearly something
tricky there).

Thanks again!

https://codereview.chromium.org/1017743002/diff/20001/net/docs/bug-triage.md
File net/docs/bug-triage.md (right):

https://codereview.chromium.org/1017743002/diff/20001/net/docs/bug-triage.md#...
net/docs/bug-triage.md:48: needed, until you can do one of the following:
The HTML output following this is still not indented :-{.

[asanka, 2015-03-18 20:47:31]

Thanks. I didn't catch the missing indentation during the last cursory scan
before I uploaded the patchset. I found another list that didn't indent properly
and fixed both.

The docs at
https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md say
that a sublist just has to be indented more than the previous parent list. But
apparently this doesn't work as advertised. I reported this as
https://code.google.com/p/gitiles/issues/detail?id=73

https://codereview.chromium.org/1017743002/diff/20001/net/docs/bug-triage.md
File net/docs/bug-triage.md (right):

https://codereview.chromium.org/1017743002/diff/20001/net/docs/bug-triage.md#...
net/docs/bug-triage.md:48: needed, until you can do one of the following:
On 2015/03/18 16:25:59, rdsmith wrote:
> The HTML output following this is still not indented :-{.

Done.

[asanka, 2015-03-18 20:48:47]

The CQ bit was checked by asanka@chromium.org

[asanka, 2015-03-18 20:48:48]

The patchset sent to the CQ was uploaded after l-g-t-m from rdsmith@chromium.org
Link to the patchset: https://codereview.chromium.org/1017743002/#ps80001
(title: " ")

[commit-bot: I haz the power, 2015-03-18 20:49:30]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1017743002/80001

[asanka, 2015-03-18 20:52:47]

rdsmith: to confirm, I did fix the indentation issue. The bug filed with Gitiles
is that the sublist required 4 spaces instead of anything more than 1.

[Randy Smith (Not in Mondays), 2015-03-18 20:52:49]

On 2015/03/18 20:49:30, I haz the power (commit-bot) wrote:
> CQ is trying da patch. Follow status at
>  https://chromium-cq-status.appspot.com/patch-status/1017743002/80001

I remain of the opinion we shouldn't land this without Matt getting to weigh
in--he owns the triage process, after all.

[asanka, 2015-03-18 20:54:05]

The CQ bit was unchecked by asanka@chromium.org

[asanka, 2015-03-18 20:54:28]

On 2015/03/18 20:52:49, rdsmith wrote:
> On 2015/03/18 20:49:30, I haz the power (commit-bot) wrote:
> > CQ is trying da patch. Follow status at
> >  https://chromium-cq-status.appspot.com/patch-status/1017743002/80001
> 
> I remain of the opinion we shouldn't land this without Matt getting to weigh
> in--he owns the triage process, after all.

Ok. Pulled off the CQ until Matt chimes in.

[mmenke, 2015-03-20 13:01:38]

On 2015/03/18 20:54:28, asanka wrote:
> On 2015/03/18 20:52:49, rdsmith wrote:
> > On 2015/03/18 20:49:30, I haz the power (commit-bot) wrote:
> > > CQ is trying da patch. Follow status at
> > >  https://chromium-cq-status.appspot.com/patch-status/1017743002/80001
> > 
> > I remain of the opinion we shouldn't land this without Matt getting to weigh
> > in--he owns the triage process, after all.
> 
> Ok. Pulled off the CQ until Matt chimes in.

LGTM.

[asanka, 2015-03-20 15:27:47]

On 2015/03/20 13:01:38, mmenke (sick) wrote:
> On 2015/03/18 20:54:28, asanka wrote:
> > On 2015/03/18 20:52:49, rdsmith wrote:
> > > On 2015/03/18 20:49:30, I haz the power (commit-bot) wrote:
> > > > CQ is trying da patch. Follow status at
> > > >  https://chromium-cq-status.appspot.com/patch-status/1017743002/80001
> > > 
> > > I remain of the opinion we shouldn't land this without Matt getting to
weigh
> > > in--he owns the triage process, after all.
> > 
> > Ok. Pulled off the CQ until Matt chimes in.
> 
> LGTM.

Cool. Thanks!

[asanka, 2015-03-20 15:27:56]

The CQ bit was checked by asanka@chromium.org

[commit-bot: I haz the power, 2015-03-20 15:28:11]

CQ is trying da patch. Follow status at
 https://chromium-cq-status.appspot.com/patch-status/1017743002/80001

[commit-bot: I haz the power, 2015-03-20 15:52:49]

Committed patchset #5 (id:80001)

[commit-bot: I haz the power, 2015-03-20 15:53:54]

Patchset 5 (id:??) landed as
https://crrev.com/ddd5dc25fc2b409c7cb5654ee6ea69e10f4d58c6
Cr-Commit-Position: refs/heads/master@{#321574}

[asanka, 2015-03-20 15:56:38]

Updated
https://sites.google.com/a/chromium.org/dev/developers/design-documents/netwo...
to point to new URLs