Nutshell review results:

Attended: bsterne, chofmann, dveditz, jesse, sicking, thunder, window
Filed: bug 414668, bug 414669, bug 414670

Status

Feature tracking bug

Firefox requirements:

• bug 392501 - Ability to customize vanilla Firefox with a group of settings
• bug 392251 - Load extensions from appdir/distribution/bundles
• bug 392499 - All distribution customizations should be localizable
• bug 392506 - Support for a low-touch interface to create customized distributions
• bug 392498 - Distribution customizations should not be profile-dependent
• bug 392504 - Support for creating customized distributions of any existing Firefox locale build
• bug 392494 - Distribution customizations should not be easily removable by end users
• bug 392502 - Customized distributions should support Windows (.exe)
• bug 411847 - About box for customized distributions doesn't show distribution name
• bug 392492 - Distribution customizations will need to be persisted across AUS updates
• bug 392500 - Customized distributions of Firefox should say so in the about box
• bug 392771 - Load search engines from appdir/distribution/searchplugins dir tree
• bug 392496 - Security and stability releases/upgrades to Firefox will be smoothly delivered without requiring customized partner builds to be generated

Installer requirements:

• bug 399665 - Support replacing BrandShortName and BrandFullName in the installer
• bug 399921 - Support replacing body text in the installer / uninstaller welcome and finish pages
• bug 399928 - Support custom shortcut names and start menu directory name
• bug 400034 - Ability to allow optional installation (check/uncheck) of bundled add-ons

Has a design review been completed?

A formal review has not been done, though the design was discussed and reviewed by bsmedberg and mconnor. Installer requirements have been reviewed (and are being implemented by) Robert Strong.

When do you anticipate the feature landing

All relevant features have landed.

Overview

Describe the goals and objectives of the feature here.

• Provide a standard, built-in way to create a customized Firefox distribution
• Make the common case very easy (prefs, bookmarks, search engines)
• Make the hard cases possible (chrome changes, addon deployment to the profile)
• Contain all changes to one directory in the appdir (distribution/)
• Do not get in the way of updates / make it possible for AUS to distribute updates to the customizations
• Make customized distributions easier to automate and test

For the installer requirements:

• Make it clear to the user that they are not installing a "vanilla" Firefox.
• Allow the user to check/uncheck additional (bundled) components.
• Allow partners to include some branding in the installer.

Use Cases

Describe the primary use cases for the feature here.

• Mozilla produces a customized version of Firefox for a specific partner
• Mozilla creates an automated system to produce customized versions of Firefox to a wide number of 3rd parties
• Users with the customized build use Firefox as usual, retaining the customizations across upgrades.

Requirements

List functional and non-functional requirements for the feature here, with links back to any relevant product PRD. These requirements should be prioritized.

All requirements are listed and prioritized on the Firefox 3 PRD:

http://wiki.mozilla.org/Firefox3/Product_Requirements_Document#Distribution http://wiki.mozilla.org/Firefox3/Product_Requirements_Document#Installer

Schedule

Describe the rough schedule here, linking back to relevant product release milestones, as well as linking to any build/release notes.

All of the distribution customizations work landed for milestones 8 and 9.

UI Design Documentation

use cases and expected user knowledge (terminology, metaphors, etc) design mockups (of whatever fidelity is easiest) links to relevant user data, bugs, reports, examples, etc

There is almost no new UI for this feature. The only exception is a string that was added to the about dialog to indicate that it was a customized build.

Design Impact

Security and Privacy

What security issues do you address in your project?

None.

Is system or subsystem security compromised in any way if your project's configuration files / prefs are corrupt or missing?

If the distribution/* files are missing, Firefox will start up as a non-customized build. If the files are there but corrupted, bad things could potentially happen [? - discuss]. Note that these files live in the appdir, not in the profile.

Include a thorough description of the security assumptions, capabilities and any potential risks (possible attack points) being introduced by your project.

The biggest risk is that by making it easier to bundle additional non-reviewed code, some distributions may add vulnerabilities to the Firefox install.

That is, the distribution features in and of themselves do not open new holes, but the underlying assumption is that we will have a wider variety of distributions, sometimes bundled with additional code/chrome (much like an extension). Thus, a bundled extension with a security hole may achieve wider distribution, and does not necessarily have to come from AMO (where presumably some code review is enforced).

Exported APIs

Please provide a table of exported interfaces (APIs, ABIs, protocols, UI, etc.)

There are no exported APIs. All configuration of the feature is done via the files in the distribution/ directory in the appdir.

Does it interoperate with a web service? How will it do so?

Not directly. It may, however, change prefs which affect how other Firefox features interact with web services. For example, it may change the AUS update URL, or modify it in part.

Explain the significant file formats, names, syntax, and semantics.

distribution.ini - INI file, sets prefs, default (additional) bookmarks. Search plugins - additional search plugins to install, separated by locale. Additional chrome - basically an extension, but not managed by the addons manager. Sample file: Distribution_INI_File

Are the externally visible interfaces documented clearly enough for a non-Mozilla developer to use them successfully?

There are no external APIs. As for the distribution.ini format and the distribution directory structure, it is not well documented (though there are some examples and such).

Does it change any existing interfaces?

No

Web Compatibility

Does the feature have any impact on Web compatibility?

No; though any bundled extensions could.

Performance

How will the project contribute (positively or negatively) to "perceived performance"?

It might delay startup slightly; particularly the first time as it adds bookmarks.

Bundled extensions can significantly alter perceived and real performance.

What are the performance goals of the project? How were they evaluated? What is the test or reference platform and baseline results?

Goals:

• No perf impact on non-customized distributions
• Minimal perf impact on customized distributions

Non-customized distributions were tested using our regular perf test suite (code has landed now, one can see graphs, etc). Customized builds were not formally perf tested; only informally. No noticeable perf hit was observed.

Will it require large files/databases (for example, browsing history)?

Potentially, any amount of new chrome could be added into the distribution directory. Common use cases, however, should be pretty small. There is no built-in requirement for any additional files in the profile.

Reliability

What failure modes or decision points are presented to the user?

No errors should ever be presented to the user. If the customizations fail to load, the user should see a vanilla Firefox. If only some subset failed to load, the user would see a mix of customized and vanilla settings.

Can its files be corrupted by failures? Does it clean up any locks/files after crashes?

No, the files live in the appdir and are read-only (save for application updates, which can potentially update the distribution/ directory).

l10n and a11y

are any strings being changed or added?

The about box has an additional string. The string is generated from the distribution.ini file, and should not have l10n impact. The distribution.ini file includes the ability to provide the about box string in multiple languages.

The distribution.ini file can also set preferences, some of which may be localizable. In that case, it allows for a 'global' value (which takes precedence over the Firefox default), as well as 'per-locale' values (which take precedence over the global value).

are all UI elements available through accessibility technologies?

There are no new UI elements, except for the about box text. I'm not sure how to test that it is available via a11y, but it should be--there is nothing special about it.

Installation, Upgrade/Downgrade/Sidegrade, and platform requirements

Does it equally support all Tier-1 platforms?

Yes

Does it have a hardware requirement (or increase minimum requirements)?

No

Does it require changes to the installer?

There are several features lumped into the "distribution customizations" umbrella. There are some requrements (under "Installer" in the Firefox 3 PRD) which are installer-related. The installer changes are P2s and not all of them are expected to land.

Does it impact updates?

Yes. There can be any number of additional files in the appdir. All new files will be contained in the distribution/ directory, meaning regular updates need not change (since they will not add/remove/replace any files in that directory).

However, files under the distribution directory may need to be updated, and to that end we have added two new fields to the AUS update URL: distribution name, and distribution version. Although AUS does not currently use them, the idea is that it could generate MARs on the fly which are specific to the distribution+distribution version the client is running.

list the expected behavior of this feature/function when Firefox is upgraded to a newer minor release, downgraded by installation of an earlier revision, or re-installed (same version)

Upgrade via software update: customizations remain untouched. Upgrade via install, downgrade, sidegrade: customizations are removed (or if installing a new customized build, those customizations take place).

This assumes that the installer will cause an uninstall before installing.

configuration

Can the end user configure settings, via a UI or about:config? Hidden prefs? Environment variables?

Not really. The user can remove the distribution/ directory from the appdir, or they can reinstall a vanilla Firefox on top, to remove any customizations.

Chrome which lives in the distribution/ directory may implement pretty much anything, and as such it may or may not be customizable.

Any additional bookmarks are added to the user's profile on first-run, and from that point on the user can modify them at will.

Are there build options for developers? [#ifdefs, ac_add_options, etc.]

No

What ranges for the tunable are appropriate? How are they determined?

N/A

What are its on-going maintenance requirements (e.g. Web links, perishable data files)?

None (?).

Relationships to other projects - are there related projects in the community?

CCK: A Firefox extension that produces an extension which can be bundled with a Firefox installer. Supports a wide range of customizations.

Benjamin Smedberg's firefox repackager: XULRunner app which can bundle an extension with a Firefox installer (for example, a cck extension)

Mozilla internal repackaging scripts / webapp: Can also generate an extension and bundle it with a Firefox installer, based on an ini configuration file (similar to, and in fact the starting point for, the distribution.ini file).

If so, what is the proposal's relationship to their work? Do you depend on others' work, or vice-versa?

This feature complements the above work by making it easier to customize Firefox. Portions of the programs above will be obsoleted (but will continue to work as-is). Specifically, Mozilla's internal partner build repackager (not the webui, but the backend scripts which generate a DEX based on an ini file) will be replaced by this feature. The CCK may be modified to better support the distribution/ tree, but doesn't need to be.

Are you updating, copying or changing functional areas maintained by other groups? How are you co-ordinating and communicating with them? Do they "approve" of what you propose?

No

Documentation

Do built-in Help pages need modified?

No

Documentation for developer.mozilla.org?

Yes, documentation for creating customized distributions will have to be modified. The approach currently described will continue to work, but the distribution/ tree is preferred.

Other

any other implementation or design related documentation

None.

Discussion & Implications

Caveats / What We've Tried Before

links to previous design documents, discussions, etc.

The other distribution customization scripts and extensions are things we have tried before. I've no other relevant links at this time.

References