Difference between revisions of "Viewer Integration and Release Processes"

From Second Life Wiki
Jump to navigation Jump to search
m
m
(6 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This page describes how Viewer development projects are organized, including the Mercurial (hg) repositories, builds, and the integration and release processes through which changes move to get from the developer (either inside or outside Linden Lab) to the Second Life Viewer.
This page describes how Viewer development projects are organized, including the git repositories, builds, and the integration and release processes through which changes move to get from the developer (either inside or outside Linden Lab) to the Second Life Viewer.
<br clear="all"/>
<br clear="all"/>
{{Project Snowstorm Nav}}
{{Project Snowstorm Nav}}
__TOC__
__TOC__
<br clear="all"/>
<br clear="all"/>
There are three core hg repositories.  Each repository is in effect a branch; the processes described here do not rely on using the hg named branches within a repository (use of named branches is discouraged):
;[[#Repo-viewer-development|viewer-development]]:is the integration working repository
;[[#Repo-viewer-beta|viewer-beta]]:records the sources in the current beta release, and may be used to repair problems in it
;[[#Repo-viewer-release|viewer-release]]:records the sources in the current stable release


== The Process ==


All three of these repositories are used by both Linden Lab development teams and open source developers; they are accessible at hg.secondlife.com.  Detailed descriptions of each, and the processes for moving changes between them, are below.
All projects begin by creating a branch in the [[#Repo-viewer|<tt>viewer</tt>]] git repository, the <tt>master</tt> branch in this repository contains the sources used to build the current default Release viewer (with the third level version number incremented by one so that any new development versions are higher numbers). Normally, Linden development project branch names begin with a Jira issue id (usually <tt>DRTVWR-''nnn''</tt> or <tt>SL-''nnnnn''</tt>), optionally followed by an underscore and some more mnemonic label.


[[Image:Viewer-Process-Overview-4.png|frameless|800px|caption="Overview of Viewer Repositories and Change Flow"]]
Viewer development proceeds with each project working from the same base and progressing through up to four phases:
# [[#Project_Integration|Project Integration]]
# [[#Beta_Test|Beta Test]] (optional)
# [[#Release_Candidate|Release Candidate]]
# [[#Release|Release]]


== Phases ==
There may be any number of projects that simultaneously have either a Project, Beta, or Release Candidate viewer available (any given project will have only one viewer available in one of those forms).


=== Development Phase ===
The Viewer Version Manager is a central service that manages notifying viewers in each channel when a newer version is available.  In Project and Beta channels, normally only one version will be available at any given time; when a new version is released by the project team, all earlier versions are invalidated so that upgrading to the newest version is mandatory.


# Developers fork from the [[#Repo-viewer-development|viewer-development]] repository to create project integration and working repositories
When the project team is ready to evaluate a Release Candidate version, a cohort is defined in the Release channel.  The Viewer Version Manager randomly selects a limited number of users and offers optional upgrades to the Release Candidate version to users in the cohort. The project team and product management evaluate the experience of users in the cohort by monitoring bugs reported against that version, its crash and frame rates, and any other appropriate metrics.
# Each project/team normally has a shared repository (which may be either public or private, according to the needs of the project) into which developers push work ready for team-level QA.
#*Project viewers are built from this branch and made available to users as appropriate.


See [[How To Submit A Viewer Change]].
When a Release Candidate is found to be of sufficiently high quality, it is promoted to Release status and becomes the default Release viewer.  The source from its project branch is then pulled to the <tt>master</tt> branch, the version number in that branch is incremented, and all other Release Candidate projects must merge those changes into their own branches and produce new Candidate versions to continue testing and be considered for promotion.


=== Integration Phase ===
[[Image:Viewer-Repo-Flow-8.png|Project Integration, Beta, and Release]]


# When team QA has passed, and the [[#Development Integration Criteria|Development Integration Criteria]] are met, the team ([[Project Snowstorm|Snowstorm]], for open source contributions) leader requests that the changes from the project repository be merged
The sections below detail the specifics of each phase.
# After review and approval, the changes are pulled into the [[#Repo-viewer-development|viewer-development]] repository (a fork of viewer-release).
#* Commits to the viewer-development repository trigger builds of Development viewers; these are available from the public wiki (but do not have a Version Manager update channel).


=== Beta Phase ===
===Project Integration===


When Linden Lab determines that the changes in viewer-development should be built as a beta candidate, one is created:
# When a project is begun, the project leader or integration engineer:
#*Creates a project branch in the [[#Repo-viewer|<tt>viewer</tt>]] repository.
#:(projects that are not yet ready to be published publicly use a branch in a Linden-private fork)
# Individual developers may create personal branches off the project branch for work that is not ready to integrate, and build [[#Channel-Test|Test]] viewers for their contributions to the project prior to integration.
#:Individual developer builds and the early project builds are <span id="Channel-Test"><tt>Second Life Test</tt></span> viewers, distinguished by the Test icon and by the dark red color of the top menu background:
#::[[Image:Viewer-Icon-Developer.png]] [[Image:Viewer-Menu-Test-2.png]]
# When individual work is ready, it is merged into the project integration branch (whether this merge is a push by individual developers or managed as a pull request to the project integration engineer is up to the project team).
# The project integration engineer maintains a canonical [[#Channel-Project|Project]] viewer build on TeamCity that builds the integration repository for QA, and may be made available to users as appropriate.
#:Project viewer builds use a distinct channel "<span id="Channel-Project"><tt>Second Life Project ''project-name''</tt></span>".  Using a Project channel causes those builds to use the Project Viewer icon and have a light blue top menu background:
#::[[Image:Viewer-Icon-Project.png]] [[Image:Viewer-Menu-Project-2.png]]


# The tag "''version''-beta''N''" is added to the current tip of the viewer-development repository, and those changes are pushed to the viewer-beta repository.
The project may decide to produce a beta release in order to do higher-risk testing and/or to get wider user testing, or it may elect to skip the [[#Beta_Test|Beta Test]] phase and proceed to directly to producing a [[#Release_Candidate|Release Candidate]].
# The viewer patch version number in indra/llcommon/llversionviewer.h is incremented (so that Development versions have higher numbers than beta viewers)
# QA does a full regression test of the resulting Beta build, including tests of all new changes.
#* If it passes QA, the build is released on the beta channel, if not repairs will be committed to viewer-beta (and pulled back to viewer-development), a new candidate will be built (with ''N'' having been incremented).


=== Release Phase ===
===Beta Test===


When Linden Lab decides that the Beta results are acceptable, the release build is begun:
Whether or not a project releases a Beta viewer is up to the project
(in recent times this has been unusual).  If the project elects to release a beta, it is built for and released on the <span id="Channel-Beta"><tt>Second Life Beta ''project''</tt></span> channel.  Using a Beta channel causes the viewer to have the beta viewer icon, and a purple menu background:
# A ''version''-release tag is added to the tip of the viewer-beta repository
:[[Image:Viewer-Icon-Beta.png]] [[Image:Viewer-Menu-Beta-1.png]]
# The contents of the viewer-beta are pushed to viewer-release, which triggers the release candidate build
# QA does a regression test on the release candidate viewer (aside from the channel, build version number, and build date, it should be identical to the most recent beta)
# The release channel is updated to the new release viewer
# Developers pull and merge all changes from viewer-release back to project and working repositories


== Repositories ==
===Release Candidate===


=== Canonical Integration and Release Repositories ===
When the Viewer Release Product Owner and project lead determine that the project has met its functional goals and it is believed to be ready for general release, the Release Candidate phase begins. Release Candidate builds use the <tt>Second Life Release</tt> channel, so they use the default icon and menu color:
:[[Image:Viewer-Icon-Release.png]] [[Image:Viewer-Menu-Release-1.png]]


;<span id="Repo-viewer-release">viewer-release</span>
Release Candidates are offered as optional updates to a randomly selected subset of users running a Release viewer. The project team and QA monitor the bugs reported against the Release Candidate, any crash reports it uploads, and the performance statistics for it to determine whether or not it is ready to be promoted to the default Release viewer.
:'''This is the primary stable code repository.'''
: [http://hg.secondlife.com/viewer-release http://hg.secondlife.com/viewer-release]
: The viewer-release repo records the code used to produce all released viewers through the latest Release version currently in production. 
: In extraordinary circumstances, fixes for especially urgent bugs may be committed directly to this repository without first going through the normal development and beta repositories below; any such changes are immediately pulled to the Development and Beta repositories.


;<span id="Repo-viewer-beta">viewer-beta</span>
It is normally the case that more than one project has a Release Candidate available.
:http://hg.secondlife.com/viewer-beta
:The viewer-beta repo is a snapshot recording the sources for the viewer currently in (or being built for) the Beta channel.
: If severe bugs are found in a beta build, fixes may be committed directly to this repository without first going through the normal viewer-development repository below; any such changes are immediately pulled back to viewer-development.


;<span id="Repo-viewer-development">viewer-development</span>
===Release===
:http://hg.secondlife.com/viewer-development
:This repo is the integration working repository; it is built continuously, with the resulting viewers being publicly available from [[Downloading test builds]] and the [[Snowstorm Team]] page.  Submissions from development projects are merged here. 


===Project Repositories===
When it is determined that a particular Release Candidate is ready, it is promoted to the default Release viewer.


Project repositories may be built as needed by the developers; viewers produced from Project repositories may be made available for public testing at times chosen by the development team.
Sources for that project are then pulled (not merged, since they are a
direct descendant) to the <tt>master</tt> branch, a <tt>''major''.''minor''.''patch''-release</tt> tag is added, the patch (third level) version number in <tt>viewer-release</tt> is incremented, and then all other projects merge those changes.


Any development, whether a single engineer fixing a minor bug or a large team building a major feature, is done in a Project repository that pulls from viewer-development.  Large projects will likely have individual repositories pulling from and pushing to their team Project repository; how this is managed and tracks changes made to Development is under the control of the developer(s) on the project.
== Mercurial Repositories ==


There may be any number of other repositories created by project teams or developers either inside or outside Linden Lab; these are ''Project'' repositories. The default channel identifier built from these repositories is "Second Life Developer".  Projects that plan to make test viewers publicly available, which is encouraged, should [[Channel and Version Requirements|change this to a project-specific value]] in those viewers.  
;<span id="Repo-viewer"><tt>viewer</tt></span>
:<tt>http://bitbucket.org/lindenlab/viewer</tt>
:The <tt>viewer</tt> repository <tt>master</tt> branch is the source used to produce all released viewers through the latest Release version currently in production.   
:''Write access to the <tt>master</tt> branch is closely controlled.''
:'''This is the stable repository and branch that serves as the base for all development.'''


Linden development teams releasing a Project Viewer should use the (internal) [https://wiki.lindenlab.com/wiki/Project_Viewer_Release_Checklist Project Viewer Release Checklist].
{{Note|The <tt>viewer-release</tt>, <tt>viewer-beta</tt> and <tt>viewer-development</tt> repositories used in earlier versions of this process are no longer used.}}


==Development Integration Criteria==
;<tt>project, beta, and candidate viewer branches</tt>
 
:The links to the branches for projects in development can be found on the [[Linden_Lab_Official:Viewer_Source_Repositories]] page.
In order to be eligible to be pulled into the Development repository, the changes in a Project repository must satisfy all of the following criteria:
 
# '''Functionality must have been reviewed and accepted by the Product Owner'''
#: Review is based on the requirements/user stories defined at the beginning of a sprint, and then at the end of a sprint during Acceptance Testing.  For Linden development teams, these checks are the normal sprint reviews, not an additional step.  For open source developers, the Snowstorm Team will coordinate these reviews with the appropriate Linden reviewers.
#: Whenever possible, any substantial change in functionality or high risk change should have been released as a Project Viewer or otherwise made available for testing by residents on the main grid prior to integration.
# '''Design and code must have been reviewed by competent reviewers.'''
#: In this context, “competent” means appropriate subject matter experts for the code that is modified.  Linden development teams determine for themselves who the competent reviewers are; for open source contributions, the Snowstorm Team will determine the appropriate reviews.  We have a public [[Code Review Tool]] for this purpose.
#:* If there are changes to code or protocols shared between the viewer and the simulator, those changes must include unit tests that at minimum validate that the behavior before and after the change is compatible. If that is not possible due to the nature of the change, then the change must include documentation on how the interfaces are changed, and the relevant simulator developers must review and approve them (for open source contributions, the Snowstorm Team will coordinate and facilitate these reviews).
# '''Any changes to strings in the user interface must have been reviewed by the documentation team.'''
# '''Any critical user interface changes must have been localized.'''
#:Critical changes are ones that could lead to serious user errors if they were unable to read the strings.  See the [https://wiki.lindenlab.com/wiki/Viewer_Localization Viewer Localization instructions] (internal) for specifics on how to get translations produced as a part of your development (open source contributors will do this through the Snowstorm Team).
# '''There must be a test plan'''
#: The test plan must describe in detail how the modified behavior can be validated and tested. We provide a handy [[Test_Script_Template|test plan template]] to help make this trouble free.
# '''The Project repository must have merged in the latest changes from Development.'''
#: In this context, "latest" means certainly within a week, and better if it is within a couple of working days.
#: The results must be validated by building viewers for all platforms and doing at least minimal viewer testing. ''Breaking the Development build is considered bad practice and may incur [http://www.ehow.com/about_5108486_karmic-debt.html karmic debt].''
#* '''There must be [http://lecs.opensource.secondlife.com/SLVcontribution_agmt.pdf Contribution Agreement]s on file from all contributors to the change if the Project repository contains changes made by non-Lindens.'''
 
When these criteria have been met, the development team may integrate into the Development repository; see [[How To Submit A Viewer Change]].

Revision as of 09:01, 30 January 2020

This page describes how Viewer development projects are organized, including the git repositories, builds, and the integration and release processes through which changes move to get from the developer (either inside or outside Linden Lab) to the Second Life Viewer.


The Process

All projects begin by creating a branch in the viewer git repository, the master branch in this repository contains the sources used to build the current default Release viewer (with the third level version number incremented by one so that any new development versions are higher numbers). Normally, Linden development project branch names begin with a Jira issue id (usually DRTVWR-nnn or SL-nnnnn), optionally followed by an underscore and some more mnemonic label.

Viewer development proceeds with each project working from the same base and progressing through up to four phases:

  1. Project Integration
  2. Beta Test (optional)
  3. Release Candidate
  4. Release

There may be any number of projects that simultaneously have either a Project, Beta, or Release Candidate viewer available (any given project will have only one viewer available in one of those forms).

The Viewer Version Manager is a central service that manages notifying viewers in each channel when a newer version is available. In Project and Beta channels, normally only one version will be available at any given time; when a new version is released by the project team, all earlier versions are invalidated so that upgrading to the newest version is mandatory.

When the project team is ready to evaluate a Release Candidate version, a cohort is defined in the Release channel. The Viewer Version Manager randomly selects a limited number of users and offers optional upgrades to the Release Candidate version to users in the cohort. The project team and product management evaluate the experience of users in the cohort by monitoring bugs reported against that version, its crash and frame rates, and any other appropriate metrics.

When a Release Candidate is found to be of sufficiently high quality, it is promoted to Release status and becomes the default Release viewer. The source from its project branch is then pulled to the master branch, the version number in that branch is incremented, and all other Release Candidate projects must merge those changes into their own branches and produce new Candidate versions to continue testing and be considered for promotion.

Project Integration, Beta, and Release

The sections below detail the specifics of each phase.

Project Integration

  1. When a project is begun, the project leader or integration engineer:
    • Creates a project branch in the viewer repository.
    (projects that are not yet ready to be published publicly use a branch in a Linden-private fork)
  2. Individual developers may create personal branches off the project branch for work that is not ready to integrate, and build Test viewers for their contributions to the project prior to integration.
    Individual developer builds and the early project builds are Second Life Test viewers, distinguished by the Test icon and by the dark red color of the top menu background:
    Viewer-Icon-Developer.png Viewer-Menu-Test-2.png
  3. When individual work is ready, it is merged into the project integration branch (whether this merge is a push by individual developers or managed as a pull request to the project integration engineer is up to the project team).
  4. The project integration engineer maintains a canonical Project viewer build on TeamCity that builds the integration repository for QA, and may be made available to users as appropriate.
    Project viewer builds use a distinct channel "Second Life Project project-name". Using a Project channel causes those builds to use the Project Viewer icon and have a light blue top menu background:
    Viewer-Icon-Project.png Viewer-Menu-Project-2.png

The project may decide to produce a beta release in order to do higher-risk testing and/or to get wider user testing, or it may elect to skip the Beta Test phase and proceed to directly to producing a Release Candidate.

Beta Test

Whether or not a project releases a Beta viewer is up to the project (in recent times this has been unusual). If the project elects to release a beta, it is built for and released on the Second Life Beta project channel. Using a Beta channel causes the viewer to have the beta viewer icon, and a purple menu background:

Viewer-Icon-Beta.png Viewer-Menu-Beta-1.png

Release Candidate

When the Viewer Release Product Owner and project lead determine that the project has met its functional goals and it is believed to be ready for general release, the Release Candidate phase begins. Release Candidate builds use the Second Life Release channel, so they use the default icon and menu color:

Viewer-Icon-Release.png Viewer-Menu-Release-1.png

Release Candidates are offered as optional updates to a randomly selected subset of users running a Release viewer. The project team and QA monitor the bugs reported against the Release Candidate, any crash reports it uploads, and the performance statistics for it to determine whether or not it is ready to be promoted to the default Release viewer.

It is normally the case that more than one project has a Release Candidate available.

Release

When it is determined that a particular Release Candidate is ready, it is promoted to the default Release viewer.

Sources for that project are then pulled (not merged, since they are a direct descendant) to the master branch, a major.minor.patch-release tag is added, the patch (third level) version number in viewer-release is incremented, and then all other projects merge those changes.

Mercurial Repositories

viewer
http://bitbucket.org/lindenlab/viewer
The viewer repository master branch is the source used to produce all released viewers through the latest Release version currently in production.
Write access to the master branch is closely controlled.
This is the stable repository and branch that serves as the base for all development.
NOTE: The viewer-release, viewer-beta and viewer-development repositories used in earlier versions of this process are no longer used.
project, beta, and candidate viewer branches
The links to the branches for projects in development can be found on the Linden_Lab_Official:Viewer_Source_Repositories page.
Retrieved from "https://wiki.secondlife.com/w/index.php?title=Viewer_Integration_and_Release_Processes&oldid=1209090"