1868233 - Write documentation for OS version targeting, add targeting attributes and helper functions to fill any holes

Status: NEW

(Firefox :: Messaging System, task, P3)

Description

[Shane Hughes [:aminomancer]]

Recently, OS version targeting has come up in several experiments. We were requested to target an experiment to exclude Windows 11 users but not Win 7-10 users. But it's not immediately obvious how to do this, because os.windowsVersion isn't well documented. It actually returns 10 for both Windows 10 and Windows 11. That means you have to target Windows 11 with os.windowsBuildNumber >= 22000, but that wasn't easy to figure out.

Now, an experiment has requested the following:

• Windows 10/11 (64-bit only)
• macOS 10.15 and up
• Linux Ubuntu 20.04 and up (not other distributions)

We don't have the capability to target by Linux distribution version numbers, but it would be good to add this if possible. While not ideal, targeting by kernel number would be better than nothing. os.macVersion works as you'd expect, but this should be documented somewhere. I think an attribute should be added that makes this stuff more useful for targeting. We're piggybacking on TelemetryEnvironment for the existing capabilities, but reporting numbers is a bit different from targeting numbers. I'd rather we have something like windowsMajorVersion: 7 | 8 | 10 | 11 than what we've been using. Then there's the request for 64-bit only, but I'm not sure we have any bitness targeting.

And in any case, all this should be documented, so that every likely permutation of OS targeting is covered and explained in a way new engineers/interns can understand without a bunch of trial & error using VMs and stuff.

So I was thinking we should endeavor to add this documentation to the targeting page, focusing not on covering the targeting attributes that currently exist, but on covering all the information an engineer would need to know to fulfill a request like this — and, if targeting attributes are missing for any of that, adding them to the source code (and documenting them too, of course). I phrased it like that since I believe approaching this from the documentation angle could help us uncover any gaps and holes in the current targeting capabilities.