Bug 224152 – Document how to use logging in WebKit

• Component: Tools / Tests
• Status: RESOLVED FIXED

[Tyler Wilcock]

Add documentation in Introduction.md about how to use logging (e.g. LOG_WITH_STREAM).

[Tyler Wilcock]

Created attachment 425096 [details]
Patch

[Tyler Wilcock]

I know Introduction.md is contentious (https://bugs.webkit.org/show_bug.cgi?id=217017), but I figure we can move the docs added in this patch elsewhere later if we want.

FWIW, I find Introduction.md to be really helpful (though I am not the targeted first patch audience anymore).  Usually I open it with an easily Ctrl-F'able purpose ("How does logging work?").  This workflow might be a little bit harder if things were split up.

[Ryosuke Niwa]

Comment on attachment 425096 [details]
Patch

View in context: https://bugs.webkit.org/attachment.cgi?id=425096&action=review

> Introduction.md:1347
> +Some places in WebKit use a macro called `LOG_WITH_STREAM`.  Here's an example invocation:

Please use a single space between sentences.

[Ryosuke Niwa]

(In reply to Tyler Wilcock from comment #2)
> I know Introduction.md is contentious
> (https://bugs.webkit.org/show_bug.cgi?id=217017), but I figure we can move
> the docs added in this patch elsewhere later if we want.

Yes, the first thing to do is to move all the necessary information in this document. We can then decide whether splitting up is the right thing to do. Given how bad existing documentation on websites and wiki have gotten, I'm skeptical of that approach. The issue is that nobody would remember to update all the places documents are out of date because it's so hard to find all the references to a given concept, policy, or process.

> FWIW, I find Introduction.md to be really helpful (though I am not the
> targeted first patch audience anymore).  Usually I open it with an easily
> Ctrl-F'able purpose ("How does logging work?").  This workflow might be a
> little bit harder if things were split up.

Right. In fact, Introduction.md is really meant for anyone contributing to WebKit who needs to figure out how to do certain things or venturing into new territory. e.g. if you had never written ref tests, there is explanation for that. If you had never dealt with GC, then there should be a section about that too. As you touch on more areas & technical concepts in WebKit, you should be able to go back to this intro doc to learn the basics.

[Tyler Wilcock]

Created attachment 425129 [details]
Patch

[Ryosuke Niwa]

Did you mean to put this up for review?

[Tyler Wilcock]

Yes, sorry!  r? now.

[EWS]

commit-queue failed to commit attachment 425129 [details] to WebKit repository. To retry, please set cq+ flag again.

[EWS]

Committed r275482: <https://commits.webkit.org/r275482>

All reviewed patches have been landed. Closing bug and clearing flags on attachment 425129 [details].

[Radar WebKit Bug Importer]

<rdar://problem/76248971>