Re: Reviews for in-tree documentation (was: Builds docs on MDN)
On Thu, Oct 19, 2017 at 6:48 PM, Daniel Veditzwrote: > On Thu, Oct 19, 2017 at 9:30 AM, smaug 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. > 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. ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
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 2017-10-19 13:13 GMT-04:00 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 > > ___ > dev-builds mailing list > dev-bui...@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-builds ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
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 ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
On Thu, Oct 19, 2017 at 9:30 AM, smaugwrote: > (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 ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
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 Tolfsena é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 > Date: June 16, 2017 15:40 > Subject: Re: Builds docs on MDN > To: dev-bui...@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-platform@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-platform > ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
Sounds very reasonable. (Hoping the r=documentation flag won't be misused ;)) On 10/19/2017 04:37 PM, Andreas Tolfsen 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/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 ZbarskyDate: June 16, 2017 15:40 Subject: Re: Builds docs on MDN To: dev-bui...@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-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Re: Reviews for in-tree documentation (was: Builds docs on MDN)
On Thu, Oct 19, 2017 at 5:37 PM, Andreas Tolfsenwrote: > 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 > Date: June 16, 2017 15:40 > Subject: Re: Builds docs on MDN > To: dev-bui...@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-bui...@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-builds > ___ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
Reviews for in-tree documentation (was: Builds docs on MDN)
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 ZbarskyDate: June 16, 2017 15:40 Subject: Re: Builds docs on MDN To: dev-bui...@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-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform