TPVD/Viewer Version Management

From Second Life Wiki
Revision as of 07:48, 15 August 2014 by Oz Linden (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

Many users do not upgrade viewers as newer versions become available, and TPV users seem to upgrade even less often than Linden viewer users. This may be because TPV developers don't have as much infrastructure to manage upgrades and enforce them. The use of large numbers of old viewer versions creates problems for the introduction of new Second Life features; even attempting to predict the potential compatibility problems, much less test for them, is intractable. It also inhibits adoption of new TPV features and requires them to worry about compatibility with much older versions.

Linden Lab provides access to our viewer version management infrastructure to TPV developers in good standing so that they have the capabilities the Lab has to encourage and enforce use of current versions.

The shared code already provides the viewer functionality needed to support automatic upgrade checks and installation; this program adds the server side capabilities by providing a way to configure TPVs in the Linden Lab Viewer Version Manager (VVM).


In order to be eligible to use the Linden Lab VVM service, a TPV must:

  • Be listed in the official Third Party Viewer Directory
  • Be primarily focused on Second Life
  • Be supporting important new Second Life functionality reasonably promptly
  • Be used by a significant user population
Yes - the requirements are deliberately "soft" - subject to a Linden Lab judgment call. In general, we want to be able to make this available to TPVs that are in good standing with the Lab. -- Oz Linden

TPVs must not query the Linden Lab update service when connecting to non-Linden grids.


A "Channel" is a named set of viewer versions. A viewer version is a set of four positive integers separated by '.' characters. See Channel and Version Requirements.

Each TPV has a Viewer Identifier value that serves as its own channel prefix (the Linden Lab Viewer Identifier is "Second Life"). The prefix can be used to create any number of unique channels by appending any suffix such as 'Release' or 'Beta' or a feature name like 'Mesh'.

Each eligible TPV may define two channel names beginning with the Viewer Identifier to be managed by the VVM:

  • Main Channel
    Such as "viewer-identifier Release"
  • Secondary Channel
    Such as "viewer-identifier Beta"

The names for these channels are recorded in the TPV Application jira issue.

Each channel may have any number of versions deployed. The newest of these is the "tip" version. Whenever a new tip version is deployed to a channel, all earlier versions in the channel are offered an optional upgrade to the new tip. The TPV developer is encouraged to specify a minimum allowed version; any viewer earlier than the minimum version is required to update to the tip version of the channel, and is not allowed to log in to Second Life.

The Main channel additionally has a 'candidate' cohort (sort of like a sub-channel). The candidate cohort may have only one active version; every time a new tip version is deployed to the candidate cohort, any earlier version from that cohort is required to upgrade.

The TPV is thus presented with three managed channels/cohorts:

  • Main Channel
    • default cohort
    • candidate cohort
  • Secondary Channel

The TPV may use these in any suitable way. For purposes of illustration, this is how Linden Lab uses channels and cohorts:

  • The Main Channel's default cohort's tip version is the release viewer. Most users run this viewer.
  • A viewer deployed to the Secondary Channel is opt-in, like a beta: a user must explicitly download and install a Secondary Channel viewer. That viewer has the Secondary Channel name baked in. Each time a new tip viewer build is deployed to the Secondary Channel, Linden requires that every previous Secondary Channel viewer version must update to the new tip version. (Bugs and/or crashes in older Secondary Channel versions aren't interesting.) Put another way, in a Secondary Channel the minimum version is the tip version.
  • The team fixes bugs and/or crashes in the Secondary Channel viewer and deploys another new tip version. Iterate on this step.
  • At some point, the development work that's been tested in the Secondary Channel becomes worth considering as a release candidate. The team builds a release candidate viewer with the Main Channel name baked in. That version is deployed to the Main Channel's candidate cohort. The candidate cohort is opt-out, therefore a release candidate viewer must be as stable as internal testing can establish. Once a new tip version is deployed to the Main Channel's candidate cohort:
    • Linden Lab requires that any previous Secondary Channel viewer must update to the new tip release candidate.
    • Linden Lab requires that any previous release candidate in the candidate cohort update to the new tip release candidate.
    • A throttled subset of users of the Main Channel's default cohort viewer will be offered updates to the new tip release candidate.
  • The team fixes bugs and/or crashes in the release candidate and deploys another new tip version to the candidate cohort. Iterate on this step.
  • When the tip release candidate has accumulated sufficient user hours to be relatively confident about its crash rate, and the crash rate is deemed acceptable, it is promoted to release.
    • The same viewer build is deployed as the new tip viewer in the Main Channel's default cohort. This is why each release candidate has the Main Channel name baked in: it is hoped that at some point it will become the release viewer.
    • Previous release candidate viewers will be updated to the new Main Channel default tip version.
    • The Secondary Channel viewers that used to be updated to the candidate cohort will now be updated to the Main Channel default tip version instead.
  • Meanwhile, yet another tip viewer has been deployed to the Secondary Channel, and the cycle continues...

When deploying a new tip version to the candidate cohort, the TPV may select:

Candidate Probability
the percentage of the upgrade requests from the Main Channel default cohort that should be offered an upgrade to the candidate (users may opt out of candidate upgrades using a preference)
Desired Cohort Size
the number of systems to be upgraded. Once the desired number of systems have logged in using the candidate version, no more are offered upgrades to the candidate.

Any channel not configured in the VVM is unmanaged: no upgrades are offered for any version and login is always allowed regardless of version. TPVs may use unmanaged channel values as well as the managed ones (but unmanaged channel builds should not be given wide distribution, or the purpose is defeated).

Version numbers must be unique within a Viewer Identifier across all channels, but each TPV has its own version-number "namespace."

How to Release a Version

Before actually posting a version where your users will get it, you should test whether or not upgrading to that version from an earlier version of your viewer works, and whether or not upgrading from that new version to some successor version will work. See Testing Viewer Upgrades.

Each viewer listed in the Third Party Viewer Directory has an Application issue in the Third Party Viewer jira project, assigned to the primary contact person between that viewer and Linden Lab.

  • The Main and Secondary channel names for your viewer must be entered on that issue; they are on the Admin tab.

Only that primary contact may make requests to deploy a new version.

To request that a new version be deployed through the VVM:

TPV Deploy Request v2.png
  1. Open the application issue for your viewer
  2. Select 'More Actions > Create Sub-Task'
  3. Select the issue type "TPV Deploy Request"
  4. Select the channel/cohort to which the new version should be deployed
  5. Fill in the 'TPV Version' to the version number (just the number; do not include the channel name)
  6. Fill in the 'Release Notes' link (this appears in some dialogs when the upgrade is offered)
  7. If desired, modify the Viewer Minimum Version
    any version less than this will be a required update to the new version, and will be barred from logging in to Second Life
  8. If you selected the 'Main Channel candidate', set the 'Channel Candidate %' and 'Desired Cohort Size' fields
    If you make the desired size larger, more users will be added; making it smaller will not remove users
  9. Fill in the installer urls for any platforms you support. Linden Lab does not provide hosting for the download urls; you can use any hosting you have available. For any platforms that are not on the form, use the comment field.
    Contact Oz if this set of platforms does not match what you need.
  10. Submit the request

The request will be automatically routed to Oz or some other Linden. You will be notified when it has been completed or it is sent back to you for clarification.