Reviews for in-tree documentation (was: Builds docs on MDN)

[Andreas Tolfsen]

Some time ago there was a discussion on dev-builds@ regarding
the state of our in-tree source code documentation. The main
focus was that MDN, moving forward, will mainly revolve around web
platform documentation and would actively start de-emphasising Gecko
contribution docs.

Now, that discussion paints the backdrop for this new thread, but it
is well worth reading on its own and had a lot of good ideas in it
that never materialised:

https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/Xqy_nHV5DAAJ

The reality four months on is that more documentation than ever
lives in the tree, and there is a sentiment that imposing the
same rigorous peer review process we have for source code on
documentation changes is overkill.

bz made a modest proposal that documentation changes should not
require bugs or reviews, and that they could be annotated with a
special review flag to pass pre-receive hooks. I’m including his
original email below.

If we still feel this is a good idea I would like to know what steps
to take next to make that policy.

-- >8 --
From: Boris Zbarsky <bzba...@mit.edu>
Date: June 16, 2017 15:40
Subject: Re: Builds docs on MDN
To: dev-b...@lists.mozilla.org

On 6/16/17 9:33 AM, Ehsan Akhgari wrote:
> I certainly feel like the barrier for filing bugs, creating a
> patch, figuring out how to use readthedocs infrastructure, getting
> reviews, etc. isn't really worth it

I believe we should not require filing bugs, reviews, or any of
that for in-tree docs. Just edit the doc, commit, push. Add
"r=documentation" if needed to placate hooks. Just because it's
in-tree doesn't mean it needs to use the whole heavyweight process.
And if we can make these things auto-DONTBUILD, that's even better,
of course.

I agree it's still slower than a wiki. :(

[Gregory Szorc]

On Thu, Oct 19, 2017 at 5:37 PM, Andreas Tolfsen <a...@sny.no> wrote:

> Some time ago there was a discussion on dev-builds@ regarding
> the state of our in-tree source code documentation. The main
> focus was that MDN, moving forward, will mainly revolve around web
> platform documentation and would actively start de-emphasising Gecko
> contribution docs.
>
> Now, that discussion paints the backdrop for this new thread, but it
> is well worth reading on its own and had a lot of good ideas in it
> that never materialised:
>
> https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJX
> TE/Xqy_nHV5DAAJ
>
> The reality four months on is that more documentation than ever
> lives in the tree, and there is a sentiment that imposing the
> same rigorous peer review process we have for source code on
> documentation changes is overkill.
>
> bz made a modest proposal that documentation changes should not
> require bugs or reviews, and that they could be annotated with a
> special review flag to pass pre-receive hooks. I’m including his
> original email below.
>
> If we still feel this is a good idea I would like to know what steps
> to take next to make that policy.
>

I am planning on implementing this. I'll probably track it off bug 1395763
somewhere. The timetable with Phabricator may hold up aspects of it a bit.

>
> -- >8 --
> From: Boris Zbarsky <bzba...@mit.edu>
> Date: June 16, 2017 15:40
> Subject: Re: Builds docs on MDN
> To: dev-b...@lists.mozilla.org
>
> On 6/16/17 9:33 AM, Ehsan Akhgari wrote:
>
>> I certainly feel like the barrier for filing bugs, creating a
>> patch, figuring out how to use readthedocs infrastructure, getting
>> reviews, etc. isn't really worth it
>>
>
> I believe we should not require filing bugs, reviews, or any of
> that for in-tree docs. Just edit the doc, commit, push. Add
> "r=documentation" if needed to placate hooks. Just because it's
> in-tree doesn't mean it needs to use the whole heavyweight process.
> And if we can make these things auto-DONTBUILD, that's even better,
> of course.
>
> I agree it's still slower than a wiki. :(

> _______________________________________________
> dev-builds mailing list
> dev-b...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-builds
>

[Sylvestre Ledru]

By the way, do we know how many mdn contributions are made on these pages
by people who are not regular Firefox developers?
A push in-tree requires permissions, which isn't a small barrier, might
impact that (not mentioning the size of the repo).
If this is only a few people, this might not be an issue.

Sylvestre

Le jeu. 19 oct. 2017 à 17:38, Andreas Tolfsen <a...@sny.no> a écrit :

> Some time ago there was a discussion on dev-builds@ regarding
> the state of our in-tree source code documentation. The main
> focus was that MDN, moving forward, will mainly revolve around web
> platform documentation and would actively start de-emphasising Gecko
> contribution docs.
>
> Now, that discussion paints the backdrop for this new thread, but it
> is well worth reading on its own and had a lot of good ideas in it
> that never materialised:
>
>
> https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/Xqy_nHV5DAAJ
>
> The reality four months on is that more documentation than ever
> lives in the tree, and there is a sentiment that imposing the
> same rigorous peer review process we have for source code on
> documentation changes is overkill.
>
> bz made a modest proposal that documentation changes should not
> require bugs or reviews, and that they could be annotated with a
> special review flag to pass pre-receive hooks. I’m including his
> original email below.
>
> If we still feel this is a good idea I would like to know what steps
> to take next to make that policy.
>

> -- >8 --
> From: Boris Zbarsky <bzba...@mit.edu>
> Date: June 16, 2017 15:40
> Subject: Re: Builds docs on MDN
> To: dev-b...@lists.mozilla.org
>
> On 6/16/17 9:33 AM, Ehsan Akhgari wrote:
> > I certainly feel like the barrier for filing bugs, creating a
> > patch, figuring out how to use readthedocs infrastructure, getting
> > reviews, etc. isn't really worth it
>
> I believe we should not require filing bugs, reviews, or any of
> that for in-tree docs. Just edit the doc, commit, push. Add
> "r=documentation" if needed to placate hooks. Just because it's
> in-tree doesn't mean it needs to use the whole heavyweight process.
> And if we can make these things auto-DONTBUILD, that's even better,
> of course.
>
> I agree it's still slower than a wiki. :(
> _______________________________________________

> dev-platform mailing list
> dev-pl...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-platform
>

[Daniel Veditz]

On Thu, Oct 19, 2017 at 9:30 AM, smaug <sm...@welho.com> wrote:

> (Hoping the r=documentation flag won't be misused ;))


​I hope there will be some kind of hook making sure files touched in that
manner are all actually documentation files and not other parts of the repo.

-
​Dan Veditz​

[Andreas Tolfsen]

Also sprach Sylvestre Ledru:

> By the way, do we know how many mdn contributions are made on
> these pages by people who are not regular Firefox developers? A
> push in-tree requires permissions, which isn't a small barrier,
> might impact that (not mentioning the size of the repo). If this
> is only a few people, this might not be an issue.

I don’t have these numbers, but gps had some thoughts on how
to potentially allow on-line GitHub editing PRs to m-c for
below-commit-level-3 changes that you can read more about in the
other thread [1]. Perhaps that is a way to make drive-by community
contributions to in-tree documentation easier.

My primary concern is to first fix the papercut of having to channel
changes to existing in-tree documentation through the same review
process as regular source code.

[1] https://groups.google.com/d/msg/mozilla.dev.builds/cp4bJ1QJXTE/MQUHhqX-DAAJ

[Dustin Mitchell]

I think we should question the assumption that writing
source-code-level documentation is a good activity for newcomers to
the codebase.

Documentation is usually best written by someone with a deep
understanding of what is being documented, not by someone new to the
project. And this documentation is developer-focused, meaning anyone
understanding its content deeply should generally be an experienced
developer.

At the most, I can see using a documentation edit as an exercise in
going through the patch / review / land process for a contributor who
I would then urge on to more substantive tasks (which may also involve
substantive doc updates).

All of which is to say, yes, I'd like to see the numbers on this and I
think we should use those numbers to think carefully about whether the
proposal merits the cost in complexity, implementation time, and
security risk.

Dustin

[Gregory Szorc]

Of course. I don't intend to create a backdoor for making changes to
Firefox :)

The authnz part of allowing contributions that aren't `hg push ssh://
hg.mozilla.org/` is hard to do right. We're very cognizant about looping in
members of jbryner's team when we design and implement changes. That will
definitely happen here at some point.