gecko.readthedocs.org "outage" and future plans

Kris Maglione kmaglione at mozilla.com
Thu Aug 24 19:46:18 UTC 2017


On Thu, Aug 24, 2017 at 12:25:32PM -0700, Gregory Szorc wrote:
>On Thu, Aug 24, 2017 at 12:18 PM, Kris Maglione <kmaglione at mozilla.com>
>wrote:
>
>> Related:
>>
>> The build environment on RTD has been one of the main things preventing us
>> from getting JSDoc comments into our Sphinx docs. Now that we have our own
>> hosting, will it be possible to add something like sphinx-js to the build
>> process?
>>
>> [1]: https://github.com/erikrose/sphinx-js
>
>
>Yes. That's sphinx-js is tracked by bug 1389341. And, yes, now that we are
>in full control over the execution environment, we can have nice things. We
>could potentially upload Doxygen, Javadoc, etc to this site as well. Maybe
>even a static version of DXR or Searchfox (if such a thing is possible).
>File Core :: Build Config bugs. I can help with technical guidance and
>reviews.

Great. Bug 1389341 is just what I'm after. I'll put converting 
more of our pseudo-JSDoc into something parsable back on my 
priority list.

Thanks

>> On Thu, Aug 24, 2017 at 12:01:39PM -0700, Gregory Szorc wrote:
>>
>>> https://firefox-source-docs.mozilla.org/ is now live.
>>>
>>> Please update your links.
>>>
>>> Send thanks to Dustin Mitchell and WebOps for all the behind-the-scenes
>>> operational work.
>>>
>>> On Tue, Aug 22, 2017 at 3:52 PM, Gregory Szorc <gps at mozilla.com> wrote:
>>>
>>> tl;dr https://gecko.readthedocs.org broke hard a few hours ago (but the
>>>> docs are still available at a temporary URL) and we have plans to move
>>>> away
>>>> from Read the Docs due to ongoing reliability and control concerns.
>>>>
>>>> The Firefox source repository has in-tree Sphinx docs. We've been hosting
>>>> those on https://gecko.readthedocs.org/ for a few years.
>>>>
>>>> In recent months, the reliability of Read The Docs (RTD) for generating
>>>> the Firefox docs has deteriorated slowly. ~50% of docs "builds" fail for
>>>> "intermittent" reasons (mostly related to the scale of our docs AFAICT).
>>>>
>>>> A few hours ago, failure to generate the docs has somehow resulted in RTD
>>>> showing a generic template page and the old docs are no longer visible.
>>>> And
>>>> instead of a useful and potentially actionable build log, it shows "An
>>>> unexpected error occurred."
>>>>
>>>> Because of the deterioration of RTD's reliability, the unplanned fire
>>>> drills that changes to RTD inflict upon us, and the inability to fully
>>>> control the docs generation environment to do advanced things, we've been
>>>> wanting to move away from gecko.readthedocs.org for several months. (For
>>>> the record, I have engaged RTD about reliability issues in the past. It
>>>> is
>>>> clear Firefox's docs are a 0.1% use case in terms of scale and therefore
>>>> difficult to support.)
>>>>
>>>> We now have TaskCluster automation uploading the generated docs whenever
>>>> they are changed on mozilla-central (bug 1382729). This is covered by
>>>> Firefox's automation "SLA" which means people notice quickly when it
>>>> breaks
>>>> (unlike RTD). The next step is bug 1392765 to get a new hostname and x509
>>>> certificate so there is a more official-looking home. From there, we'll
>>>> likely do some things around hosting different versions corresponding to
>>>> Firefox releases (bug 1390693) and auto-generated documentation for
>>>> JavaScript files courtesy of sphinx-js (bug 1389341). And, yes, we'll
>>>> likely try to redirect gecko.readthedocs.org to the new home so old
>>>> links
>>>> still work.
>>>>
>>>> I'll send out an announcement when we have a new formal home for the
>>>> in-tree docs (hopefully in a few days). In the mean time, if you must
>>>> access the docs that were formerly available at
>>>> https://gecko.readthedocs.org/, you can find them at
>>>> http://gecko-docs.mozilla.org.s3.amazonaws.com/index.html. That's a
>>>> temporary home, so please don't link to it from anything official.
>>>>
>>>> I apologize for any inconvenience this has caused. The service
>>>> reliability
>>>> problems should go away once we complete the transition from RTD to
>>>> TaskCluster.
>>>>
>>>

-- 
Kris Maglione
Senior Firefox Add-ons Engineer
Mozilla Corporation

Perspective is worth 80 IQ points.
	--Alan Kay



More information about the firefox-dev mailing list