Closed Bug 1325121 Opened 6 years ago Closed 4 years ago

Properly document stub installer ping

Categories

(Firefox :: Installer, defect, P1)

defect

Tracking

()

RESOLVED FIXED
Firefox 60
Tracking Status
firefox60 --- fixed

People

(Reporter: gfritzsche, Assigned: mhowell)

References

Details

(Whiteboard: [fce-active-legacy])

Attachments

(1 file)

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
Flags: needinfo?(rtestard)
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.
Priority: -- → P3
(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.
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.
Flags: needinfo?(rtestard)
We should document the data that we send in pings.
Is the stub installer ping data documented somewhere?
Flags: needinfo?(rtestard)
(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.
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.
Flags: needinfo?(rtestard)
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.
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.
Flags: needinfo?(rvitillo)
Whiteboard: [fce-active]
Flags: needinfo?(rvitillo) → needinfo?(rharter)
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.
Flags: needinfo?(rharter) → needinfo?(rtestard)
(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
Flags: needinfo?(rtestard)
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
Whiteboard: [fce-active] → [fce-active-legacy]
Assignee: nobody → mhowell
Priority: P3 → P1
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
Attachment #8953171 - Flags: review?(agashlin) → review+
Pushed by mhowell@mozilla.com:
https://hg.mozilla.org/integration/autoland/rev/cdf9965aa9b9
Add some installer documentation to the tree. r=agashlin
https://hg.mozilla.org/mozilla-central/rev/cdf9965aa9b9
Status: NEW → RESOLVED
Closed: 4 years ago
Resolution: --- → FIXED
Target Milestone: --- → Firefox 60
You need to log in before you can comment on or make changes to this bug.