1325121 - Properly document stub installer ping

Status: RESOLVED FIXED

(Firefox :: Installer, defect, P1)

Description

[Georg Fritzsche [:gfritzsche]]

There is documentation for the contents here:
https://bugzilla.mozilla.org/show_bug.cgi?id=899363#c19

We should properly document the ping under:
toolkit/components/telemetry/docs/data

Comment 1

[Benjamin Smedberg]

I suggest that in the source tree the docs should live next to the code, so somewhere in browser/installer. That way doc ownership and responsibility for future changes is more clear.

Comment 2

[Georg Fritzsche [:gfritzsche]]

(In reply to Benjamin Smedberg [:bsmedberg] from comment #1)
> I suggest that in the source tree the docs should live next to the code, so
> somewhere in browser/installer. That way doc ownership and responsibility
> for future changes is more clear.

We should still at least have them discoverable in one location.
We can e.g. cross-link them from telemetry/docs/data/index.rst.

Comment 3

[Romain Testard [:RT]]

Clearning the NI, I documented what's in redash but the fields are different so the best reference must be https://bugzilla.mozilla.org/show_bug.cgi?id=899363#c19.

Comment 4

[Georg Fritzsche [:gfritzsche]]

We should document the data that we send in pings.
Is the stub installer ping data documented somewhere?

Comment 5

[Georg Fritzsche [:gfritzsche]]

(In reply to Georg Fritzsche [:gfritzsche] from comment #4)
> We should document the data that we send in pings.
> Is the stub installer ping data documented somewhere?

I.e. somewhere that is not bugzilla, discoverable and can be linked to from our telemetry documentation.

Comment 6

[Romain Testard [:RT]]

Not that I know of but what's on https://bugzilla.mozilla.org/show_bug.cgi?id=899363#c19 seems to cover it all so we probably just need to make the content of c19 available in browser/installer. 
There is a lot going on in the installer in the next couple of weeks and Matt probably set the priority right.

Comment 7

[Molly Howell (she/her) (mostly inactive)]

I wrote this up a while back, but I put it in a Google doc [https://docs.google.com/document/d/1HKFETH8sJEaTs7vUj6RX96gO5heLw6eDncRhgQbNSuI]. This should at least be linked to in-tree, and really preferably maintained there.

Comment 8

[David Durst [:ddurst]]

Is there a place that we can document things about this data as it appears in re:dash? Documenting the ping is great, but for people querying it in re:dash, it could become confusing.

Comment 9

[Ryan Harter [:harter]]

Romain, can you link me to the documentation you mention in C3?

For now, the best place to document data quirks is either:
* telemetry-batch-view/docs/ if the data is coming from Presto, or
* Custom Dashboards with Re:dash[0] if the data's from some other source.

That being said, we're in the process of reworking our documentation (Bug 1329840).
I'll add this documentation task to the list of use cases in that bug.

Comment 10

[Romain Testard [:RT]]

(In reply to Ryan Harter [:harter] from comment #9)
> Romain, can you link me to the documentation you mention in C3?
> 
It's on https://docs.google.com/document/d/1zsiuP66n9Aw1klBrm83x9eaFprc7QfjwpjPFWkb1Fxw/edit

Comment 11

[Ryan Harter [:harter]]

I've added Romain and Matt's documentation to the Re:dash documentation [1]


[1] https://wiki.mozilla.org/Telemetry/Custom_dashboards_with_re:dash

Comment 12

[Molly Howell (she/her) (mostly inactive)]

Attachment: Bug 1325121 - Add some installer documentation to the tree.

This is not exhaustive technical documentation for every aspect of the installer
code, but it's better than what we had, and it does contain the ping
documentation that this bug was originally asking for.

Review commit: https://reviewboard.mozilla.org/r/222448/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/222448/

Comment 13

[Adam Gashlin (he/him) [:agashlin] (ex-moco)]

Comment on attachment 8953171 [details]
Bug 1325121 - Add some installer documentation to the tree.

https://reviewboard.mozilla.org/r/222448/#review228702

::: browser/installer/windows/docs/Helper.rst:16
(Diff revision 1)
> +
> +Note that profiles and any other user-generated files (e.g., crash reports) are specifically not uninstalled.
> +
> +PostUpdate
> +----------
> +At the end of an application update cycle, after the new files are in place, the updater invokes the helper with the ``/PostUpdate`` commnad-line switch. The PostUpdate function fills a grab bag of responsibilities which are all focused around maintaining system integration objects created by the installer. For example, a number of registry entires contain the version number, so that has to be changed on updates. If the branding name of the application changes and shortcuts have to be renamed, that's done here as well. For one counterexample, changing icons does not require any code in PostUpdate, or anywhere else; new icons are automatically picked up by the shell. The PostUpate function also keeps the maintenance service up to date.

PostUpate -> PostUpdate

::: browser/installer/windows/docs/Helper.rst:18
(Diff revision 1)
> +
> +PostUpdate
> +----------
> +At the end of an application update cycle, after the new files are in place, the updater invokes the helper with the ``/PostUpdate`` commnad-line switch. The PostUpdate function fills a grab bag of responsibilities which are all focused around maintaining system integration objects created by the installer. For example, a number of registry entires contain the version number, so that has to be changed on updates. If the branding name of the application changes and shortcuts have to be renamed, that's done here as well. For one counterexample, changing icons does not require any code in PostUpdate, or anywhere else; new icons are automatically picked up by the shell. The PostUpate function also keeps the maintenance service up to date.
> +
> +It's important to remember that PostUpdate is, indeed, post-update. It doesn't run until after its own code has already been updated. This makes it really the only phase of the update process where changes can go into affect immediately in the first build that contains a patch, instead of having to wait for the next update after that. This makes it a good place to put anything that needs to be done before the new version of the application can run; this includes things like registering DLL's, which the installer also handles, but that PostUpdate has to take care of for existing installation.

nit: "for an existing installation"?

::: browser/installer/windows/docs/StubInstaller.rst:5
(Diff revision 1)
> +==============
> +Stub Installer
> +==============
> +
> +The stub installer is the default installer interface that most users installing Firefox will see. It's a tiny download (200-300 KB), so it gets the user into the product experience quickly. It's also a highly streamlined experience; there are no options or prompts offered, except in the case of a returning user (see Profile Cleanup). Running the stub installer immediately starts downloading and installing the browser, and automatically runs the new installation and exits when its done.

nit: "when it's done."

::: browser/installer/windows/docs/StubPing.rst:5
(Diff revision 1)
> +=========
> +Stub Ping
> +=========
> +
> +When the stub installer completes with almost any result[1]_, it generates a ping containing some data about the system and about how the installation went. This ping isn't part of Firefox unified telemetry, it's a bespoke system; we can't use the telemetry client code when it isn't installed yet.

a space is needed before the footnote link (at least when I ran it through Sphinx v1.6.7), same with [2] below

Comment 14

[Molly Howell (she/her) (mostly inactive)]

Comment on attachment 8953171 [details]
Bug 1325121 - Add some installer documentation to the tree.

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/222448/diff/1-2/

Comment 15

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/cdf9965aa9b9
Add some installer documentation to the tree. r=agashlin

Comment 16

[Sebastian Hengst [:aryx] (needinfo me if it's about an intermittent or backout)]

https://hg.mozilla.org/mozilla-central/rev/cdf9965aa9b9