Skip to content

Commit 354d032

Browse files
jaredlockhartclaude
jaredlockhart
and
claude
authored
Add Firefox Labs documentation (#777)
* chore: add Firefox Labs documentation Because * Firefox Labs documentation currently only exists in internal Google Docs * Teams need a public reference for how to configure and launch Labs experiences * Technical details about Labs fields, graduation, and FAQ are not documented This commit * Adds a workflow article covering what Labs is, when to use it, the setup checklist, Experimenter field reference, graduation process, and marketing * Adds a dedicated Firefox Labs FAQ page * Adds both pages to the sidebar navigation fixes #776 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: address review feedback on Firefox Labs article Because * Beth reviewed and flagged that there won't be a Labs PM going forward * The Merge/release timeline wording needed clarification about uplifts * New Labs groups need a note about riding release trains This commit * Replaces all "Labs PM" / "Product Manager" references with #firefox-labs channel * Updates timeline example to mention uplifts as an option * Adds note that new Labs groups must ride the release trains Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: call out String Freeze milestone explicitly Because * Reviewer flagged that String Freeze is a specific release milestone that should be called out by name since Labs features require landing Fluent strings before the freeze This commit * Adds explicit mention of String Freeze (Nightly W4 Friday) with a link to the shipping guide documentation * Updates the milestone list to read "String Freeze, Soft Code Freeze, and Merge" instead of just "Soft Freeze and Merge" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent c55845d commit 354d032

3 files changed

Lines changed: 270 additions & 2 deletions

File tree

‎docs/faq/firefox-labs-faq.mdx‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
id: firefox-labs-faq
3+
title: Firefox Labs
4+
slug: /faq/firefox-labs
5+
sidebar_position: 3.5
6+
---
7+
8+
Common questions about Firefox Labs experiences, telemetry, marketing, and interaction with experiments and rollouts.
9+
10+
---
11+
12+
## Can I make changes to my Labs feature off-train from the release channel?
13+
14+
Once a Labs rollout has been signed off and launched, the only changes you can make to the live rollout are:
15+
16+
- **Adjusting the population percentage** (the "Percentage of clients" on the Audience page).
17+
- **Ending enrollment** to stop new opt-ins (see [Graduating a Labs feature](/workflow/firefox-labs#graduating-a-labs-feature)).
18+
19+
Any other changes require ending the existing rollout and launching a new one.
20+
21+
Keep in mind: once you put something in Release, users get the code in-tree. If you expect an opportunity to iterate based on user feedback, what they get on Day 1 will sit until Day 1 of the next release version.
22+
23+
---
24+
25+
## What kind of telemetry is available in Labs?
26+
27+
It's important to transition existing telemetry from legacy to Glean and track which checkboxes are clicked. The Glean team can help determine requirements.
28+
29+
---
30+
31+
## How do we market features available in Labs?
32+
33+
Each Labs feature is encouraged to create a dedicated Mozilla Connect thread, giving it public exposure from the start. See [Marketing your Labs feature](/workflow/firefox-labs#marketing-your-labs-feature) for available channels.
34+
35+
---
36+
37+
## What happens if a user has telemetry turned off?
38+
39+
As of Firefox 148, users can retain access to Firefox Labs if they disable telemetry. Rollouts and Labs experiences have been decoupled from telemetry so that browser enhancements and fixes can reach a larger user population. (See more on the [Remote Improvements](https://support.mozilla.org/en-US/kb/remote-improvements) choices.)
40+
41+
However, Labs will **not** appear for users who have opted out of "Install and run studies" in `about:preferences`. If the user has opted out of studies, the Labs section in Settings will show up as a blank screen.
42+
43+
---
44+
45+
## What does success look like for a Labs experience?
46+
47+
Since Labs promotes qualitative metrics, success is measured through Connect feedback, engagement metrics, and bug tickets — anything we can collect as learnings, especially ones we could share in public-facing product communications. Labs feature opt-ins are expected to be small since this appeals to early adopter users who skew more towards being technically-savvy.
48+
49+
---
50+
51+
## Can I run an experiment and/or rollout at the same time as a Labs experience?
52+
53+
Labs are configured as rollouts, so you *can* be in an experiment and a Labs experience at the same time. However, the experiment will take precedence over the Labs experience and override anything that the Labs experience established. If you end up in experiment:control, you will have opted in and your feature will no longer work.
54+
55+
You will need to choose between running a Labs experience and running a rollout at a given point in time, since people won't be able to enroll in the rollout if they're in the Labs experience, and vice versa.
56+
57+
**Preferred approach:** If you are going to launch an experiment and a Labs experience at the same time, launch the experiment *first* and then exclude the experiment population from the Labs experience so that the Labs toggle doesn't show up in `about:preferences#experimental` for users who shouldn't see it.
58+
59+
---
60+
61+
## Can I retarget a client who has opted into a Labs experience for a different experiment/rollout?
62+
63+
While Labs experiences may target 100%, users do not count as enrolled unless they opt in, so you can use normal "include" targeting to target a survey or experiment to users that were in a Labs experience.
64+
65+
---
66+
67+
## What happens if I'm already enrolled in an experiment?
68+
69+
You won't see the Labs experience affiliated with the same feature, since enrollment in an experiment takes precedence over a Labs experience.

‎docs/workflow/firefox-labs.mdx‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
id: firefox-labs
3+
title: Firefox Labs
4+
slug: /workflow/firefox-labs
5+
---
6+
7+
# Firefox Labs
8+
9+
:::tip
10+
Have questions about Firefox Labs?
11+
Reach out in [`#firefox-labs`](https://mozilla.slack.com/archives/firefox-labs) or [`#ask-experimenter`](https://mozilla.slack.com/archives/CF94YGE03) on Slack.
12+
:::
13+
14+
Firefox Labs is part of the [Nimbus platform](https://experimenter.info/) and is available on Nightly, Beta, and Release. It is a delivery mechanism that allows product development teams at Mozilla to expose feature opt-ins via a user-friendly interface in **Settings > Firefox Labs** (`about:preferences#experimental`).
15+
16+
Firefox Labs gives product development teams in Firefox an opportunity to:
17+
18+
- **Share work in progress** with the Firefox community to solicit feedback *before* the work is polished or stable enough for a larger audience.
19+
- **Gather qualitative feedback** from early adopters *instead of* (or before) running a Nimbus experiment.
20+
- **Explore experimental ideas** without disrupting the baseline user experience.
21+
- **Showcase contributor improvements** to Firefox and foster relationships with code contributors.
22+
23+
## Is Firefox Labs right for what I'm building?
24+
25+
Labs is integrated into Nimbus (**Desktop-only** for now). In the product lifecycle, Labs fits into the Incubation/Early Stage phase: if a product team is developing a new feature, Labs can serve as the first stage of product development through Nimbus.
26+
27+
However, Labs is **not built** to gather statistically significant insights like other Nimbus experiments do. Instead, Labs is built to:
28+
29+
- Gather feedback from early adopters *before* you launch a Nimbus experiment or rollout (or *instead* of running one).
30+
- Observe the behavior of the early adopter population via feature-level dashboards (Nimbus will not provide in-depth feature-level dashboards for Labs features).
31+
32+
### Labs vs. Experiments and Rollouts
33+
34+
| Scenario | Labs | Experiment / Rollout |
35+
| :--- | :---: | :---: |
36+
| "We want this feature for everyone, but we're figuring out a few things and don't want to turn it on for everyone yet." | ✅ | |
37+
| "We want to expose this feature to a representative sample and evaluate usage/engagement." | | ✅ |
38+
| "We've done internal QA, but want a short smoke test to a few hundred thousand users before going bigger." | | ✅ (Rollout) |
39+
| "We're okay if testers tend to be early adopters and more technical." | ✅ | |
40+
| "We want qualitative feedback to fine-tune the next iterations of our feature." | ✅ | |
41+
| "We want to observe quantitative engagement metrics and the causal effects of a feature." | | ✅ |
42+
| "We want to set expectations that the project isn't finished, but signal it's usable enough to test." | ✅ | |
43+
| "We're ready to roll out the feature to lots of users." | | ✅ (Rollout) |
44+
| Feature exposure can be targeted by region, locale, release train, and more. | ✅ | ✅ |
45+
| A user proactively chooses to opt into an early version of a feature in Settings. | ✅ | |
46+
| A user may be enrolled as part of a select group/branch (unless they've opted out of telemetry). | | ✅ |
47+
| A user can directly share feedback via a dedicated Connect thread. | ✅ | |
48+
| User behavior can be observed via a feature-level dashboard. | ✅ | |
49+
| User engagement can be observed through a traditional Nimbus dashboard. | | ✅ |
50+
51+
52+
## Getting started
53+
54+
### Before you begin
55+
56+
**The feature experience you're offering doesn't have to be perfect!** Labs is an external Foxfooding channel. Think of it as opening your feature up as a demo for an early access, open beta playtest — it's okay if it's incomplete or buggy. You're getting this draft version to users faster so you can get qualitative feedback earlier.
57+
58+
Although you can technically launch a Labs recipe anytime your MVP code is ready to use, you must land your strings according to the release schedule. These strings make up your feature's Labs entry title and description that appear on `about:preferences#experimental`. In particular, **[String Freeze](https://firefox-source-docs.mozilla.org/contributing/pocket-guide-shipping-firefox.html)** occurs on the Friday of Nightly Week 4 — after that point, string additions or changes are not allowed so localizers can finish translations before Merge Day. **Please factor in String Freeze, Soft Code Freeze, and Merge when considering your project timelines.** For example, if you don't get this early-stage work landed before 150 merges to Beta, you won't be able to use your feature with Firefox Labs on Release 150 without uplifts.
59+
60+
If you have the strings and feature work available in Nightly, you can use Labs on Nightly instead. Same for Beta. While the audiences for both aren't Release-minded, you can still get your feature out to a subset of users early and get qualitative feedback.
61+
62+
### What we ask of you
63+
64+
1. Walk through the checklist below to learn about the process.
65+
2. Come with a clear plan (or at least a clear hypothesis) with questions you'd like Labs testers to answer, and start filling out a [Labs Experience Brief](https://docs.google.com/document/d/1-rRI-nOLCJsN13M6gkt22f3FO5lAdm7k2C7P1N5Ar08/edit).
66+
3. If you're planning to follow up with a Nimbus experiment, clarify which hypotheses you are looking to validate/refute. What you seek to learn from Labs will likely be different from an experiment.
67+
68+
## Checklist: Getting your feature on Labs
69+
70+
### 1. Determine fit
71+
72+
Review the "Is Firefox Labs right for what I'm building?" section above to confirm Labs aligns with your goals.
73+
74+
### 2. Chat with the Labs team (optional)
75+
76+
Reach out in **#firefox-labs** on Slack to discuss your feature, preliminary timeline, and early access/GTM goals. Topics to cover:
77+
78+
- When you expect your feature will be code-complete as a Labs prototype (early-stage, but ready for a small group of users to opt into).
79+
- Whether you're planning another Nimbus delivery (e.g., experiment or rollout with randomized enrollment).
80+
- When you expect your feature to be ready to ship to the Release population.
81+
82+
### 3. Submit a Labs Experience Brief
83+
84+
If your goals align with what Labs can offer, fill out and submit a [Labs Experience Brief](https://docs.google.com/document/d/1-rRI-nOLCJsN13M6gkt22f3FO5lAdm7k2C7P1N5Ar08/edit).
85+
86+
### 4. Join #firefox-labs
87+
88+
Join the **#firefox-labs** Slack channel for your dedicated thread/canvas.
89+
90+
### 5. Attend a kick-off meeting (optional)
91+
92+
Join a Labs experience kick-off meeting coordinated via **#firefox-labs**. Consider inviting your principal engineer and UX designer.
93+
94+
### 6. Set things up for the Nimbus team
95+
96+
- **Add your feature to the Nimbus feature manifest.** You can frontload this entry with placeholders if the feature work isn't complete. See [Feature Definition](/technical-reference/feature-definition) for details.
97+
- **Land Fluent ID strings** for the title and description of the feature in [`features.ftl`](https://searchfox.org/mozilla-central/source/toolkit/locales/en-US/toolkit/firefoxlabs/features.ftl). ([Example bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1950407))
98+
- **(Optional)** If you wish to add a Connect post link placeholder such as hyperlinked "Share feedback" text in the description, include an `<a>` with no `href` in the string.
99+
- **Land the actual implementation** of the prototype.
100+
101+
### 7. Self-test QA (strongly encouraged)
102+
103+
Please self-test QA your feature at the UX level. If you plan to share the Labs experience with multiple locales, please arrange for l10n.
104+
105+
### 8. Set up a Connect feedback post (optional)
106+
107+
Want to add a direct link to your Connect feedback post from Labs? Draft the post and coordinate in **#firefox-labs** to keep it hidden until your planned Labs launch. Make sure the strings you land in-tree include a link, even if it's a placeholder for now.
108+
109+
### 9. Configure the rollout on Experimenter
110+
111+
1. Pick the **Labs section** you want to house your feature (e.g., "Customize Browsing").
112+
2. Go to [Experimenter](https://experimenter.services.mozilla.com/nimbus/) and select **Create Experiment** to create a Nimbus recipe.
113+
3. For easier tracking, **title the beginning of your Nimbus recipe** with `[Firefox Labs]` and clarify which channel this experience is on (e.g., `[Firefox Labs] Link Previews (Nightly)`).
114+
4. **Choose the channel** you want this Labs experience to launch with (e.g., Nightly). As a best practice, select one channel per recipe.
115+
116+
#### Configure the Branches section
117+
118+
5. **Classify your recipe as a rollout.** Experimenter will automatically enable the "Prevent enrollment if users have changed any prefs" setting for all rollouts.
119+
120+
6. **Check the "Is this a Firefox Labs rollout?" checkbox** on the Branches page. This will reveal several additional fields:
121+
122+
- **Title (Fluent ID)** *(required)* — The Fluent ID for your feature's title in Labs (e.g., the ID you landed in `features.ftl`). Firefox resolves this to localized text in `about:preferences#experimental`.
123+
- **Description (Fluent ID)** *(required)* — The Fluent ID for your feature's description.
124+
- **Description Links (JSON)** *(optional)* — A JSON object that maps link names to URLs, enabling clickable links inside your description. For example, if your Fluent description string contains `<a data-l10n-name="connect-link">Share feedback</a>`, provide:
125+
```json
126+
{
127+
"connect-link": "https://connect.mozilla.org/t5/your-post/..."
128+
}
129+
```
130+
All values must be HTTP(S) URLs.
131+
- **Firefox Labs Group** *(required)* — Which section your feature appears under in Labs. Available groups:
132+
133+
| Group | Minimum Firefox Version |
134+
| :--- | :--- |
135+
| Customize Browsing | 137 |
136+
| Webpage Display | 137 |
137+
| Developer Tools | 137 |
138+
| Productivity | 143 |
139+
140+
New groups can be added, but they must ride the release trains — a new group won't be available on Release until the version it was added in reaches Release.
141+
142+
- **Requires restart** *(optional)* — Check this if the feature requires a Firefox restart to take effect after the user opts in.
143+
144+
:::note
145+
When you add your feature to the Nimbus feature manifest, you can pull in the latest changes immediately from `FeatureManifest.yaml`. However, automated Experimenter syncs with the latest Nightly updates [require approval](https://github.com/mozilla/experimenter/pull/12274) before features show up in the Experimenter feature config. Once approved, the change should be available within an hour.
146+
:::
147+
148+
### 10. Launch
149+
150+
Send your Labs experience to review and launch your Nimbus recipe on Experimenter. If you wrote a Labs Connect post, coordinate in **#firefox-labs** to publish it publicly.
151+
152+
## Graduating a Labs feature
153+
154+
When a Labs feature is ready to become a default part of Firefox, you need to "graduate" it — stop new users from opting in via Labs while the feature ships as a built-in default on the next train.
155+
156+
Unlike regular rollouts, Labs rollouts support **ending enrollment**. This allows you to close opt-ins for your Labs experience while keeping existing opted-in users enrolled until the feature ships natively. To end enrollment, use the "End Enrollment" button on your rollout's summary page in Experimenter. This goes through the standard review and approval flow.
157+
158+
Once the feature has shipped as a default in a new Firefox version, you can fully end the Labs rollout.
159+
160+
## Marketing your Labs feature
161+
162+
If you currently have a feature being previewed in Labs, please avoid promoting any public interaction with your feature outside of Labs (such as an isolated try-build or add-on). If you need to promote the feature apart from Labs due to a special case, please consult in **#firefox-labs** first, and *then* the Nimbus team if needed.
163+
164+
Available marketing channels through the standard Labs process:
165+
166+
- A dedicated **Mozilla Connect** post for your Labs feature
167+
- [**Skylight messaging**](https://mozilla-hub.atlassian.net/wiki/spaces/FPS/pages/555319399/Messaging+System+Improvements) (in-product announcements)
168+
- **Release notes** (`#release-notes`)
169+
- **Firefox Socials** content (`#social-requests`)
170+
171+
## FAQ
172+
173+
See the [Firefox Labs FAQ](/faq/firefox-labs) for common questions about telemetry, marketing, running experiments alongside Labs, and more.
174+
175+
## Further reading
176+
177+
- [Early Access Opt-in](https://docs.google.com/document/d/1jNC2U39BhtmnHRNT4Csc7WvIG7ops3p4XuaCIMhlMQI/edit#heading=h.rlaew8j3mttt)
178+
- [Ways to ship a change to Firefox](https://docs.google.com/document/d/13EU2B4hqt9x7z4g5ApF0AEWMPBpFPnrSf6dQ6kuEePM/edit#heading=h.b49vdikc5pel)
179+
- [RFC: Firefox Labs x Nimbus](https://docs.google.com/document/d/1Nl5-bhhQBkStS7qzrY-o6btjJ0HLjdERrLt9p03ZSB8/edit) (engineering document for Nimbus hookup)

‎sidebars.js‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,27 @@ module.exports = {
3030
items: [
3131
"workflow/overview",
3232
"workflow/experimenter-console",
33-
"workflow/designing",
34-
"advanced/rollouts-deep-dive",
33+
{
34+
type: "category",
35+
label: "Designing",
36+
items: [
37+
{
38+
type: "doc",
39+
label: "Experiments",
40+
id: "workflow/designing"
41+
},
42+
{
43+
type: "doc",
44+
label: "Rollouts",
45+
id: "advanced/rollouts-deep-dive"
46+
},
47+
{
48+
type: "doc",
49+
label: "Firefox Labs",
50+
id: "workflow/firefox-labs"
51+
}
52+
]
53+
},
3554
"workflow/configuring",
3655
"workflow/localization",
3756
{
@@ -257,6 +276,7 @@ module.exports = {
257276
"faq/getting-started-faq",
258277
"faq/experiment-lifecycle-faq",
259278
"faq/rollouts-faq",
279+
"faq/firefox-labs-faq",
260280
"faq/targeting-audiences-faq",
261281
"faq/data-metrics-analysis-faq",
262282
"faq/platform-specific-faq"

0 commit comments

Comments
 (0)