How To Submit A Viewer Change

From Second Life Wiki
Jump to navigation Jump to search

This is not the place to start if you want to change the Viewer.
If you are interested in proposing a Viewer feature or modification, see How To Propose A Viewer Feature.


This page is one part of the Viewer Integration and Release Processes and, before you belong here, you should already have gotten your proposed change accepted (strictly speaking, if you want to do the work of implementing the change first, that's up to you, but you still have to go back and get the idea accepted before you submit the code).

For general advice on how to prepare changes so that they can get through the review and submission process easily, see Submitting code.


Submitting an Integration Request


Commit access to the viewer-development repository is managed by the Snowstorm team.

A full description of the Snowstorm workflow is below. The criteria to be met before submitting an integration request, and complete instructions for completing a merge request, are described in the following sections.

Readiness Criteria


Changes must meet all of the Development Integration Criteria before it can be pulled to the Development repository.

  1. Functionality must have been reviewed and accepted by the Product Owner:
    Normally, this means that the item must be on the current Sprint Backlog for the Snowstorm Project Team or some other Linden viewer development team, and has been reviewed by the Product Manager for that team. See How To Propose A Viewer Feature.
  2. Design and code must have been reviewed by competent reviewers.
    Reviewer(s) must be identified in the Jira item(s) used to track the change.
    The strongly preferred way to review code is to post the change on the Code Review Tool site.
  3. There must be a test plan
    The test plan must describe in detail how Integration QA can validate the modified behavior.
    • For bug fixes, putting the test plan into a Jira comment is acceptable (since the issue should already contain a documented way to reproduce the problem, this should not be much new work).
    • For features, links to wiki pages are preferred.
    • For features especially, building and distributing a viewer from the Project repository for live testing is strongly encouraged.
  4. The Project repository must have merged in the latest changes from Development.
    The results must be validated by building viewers for all platforms and doing at least minimal viewer testing.
  5. There must be a Contribution Agreement on file from each contributor to the change that is not a Linden employee or contractor.
    • External contributions must include the appropriate updates to doc/contributions.txt
    • If you already have one or more entries in contributions.txt, add new ones at the appropriate positions (sorting yours, if desired).


Linden Submissions


After the code has met all of the above-stated Readiness Criteria (all code and product owner review is complete), submit a Merge Request issue in the Snowstorm Jira project to have the Snowstorm team integrate your change(s) into the viewer-development repository. The process for creating a Merge Request is described below.

  1. Login to your Jira account
  2. Create a new issue; Project Viewer Integration, Issue Type Merge Request
  3. Enter a meaningful Summary (e.g. 'Merge Soft-Body Physics project'), not "Please merge my changes"
  4. In the Branch/Repo Fixed In field, select the repository to which your change should be merged. Normally this is viewer-development or viewer-beta; this should be the same as the one you cloned to do the work. Do not select a version number — that will be set later by the Release Manager.
  5. In the Description, highlight any potential areas of conflict

Note that, by default, all issues in the Snowstorm Jira project are visible to the public.

When your issue is complete, execute the Submit for Review transition.

This image shows the workflow for Merge Request issues (green = development, blue = product managment, purple = viewer integration, orange = QA ):

ViewerMergeWorkflow.png

Open Source Submissions


Open source contributors should be working on issues that are already in the Snowstorm project and on the Sprint Backlog, so the issues involved should already be in the Snowstorm project. For these issues, execute the Ready For Review transition.

When you execute that transition, you will be prompted for the following two fields, which you should be prepared to fill in (or you should have already edited them into the issue):

Branch/Repo Fixed In
This should be the url of a publicly visible (preferably bitbucket.org) hg repository that is a clone of the current viewer development with the change for this issue (and _only_ this issue) added to it.
Code Review
This should be the URL of a review of that same change posted at codereview.secondlife.com (see Code Review Tool)


Snowstorm Workflow Detail


The sections below describe the workflow for issues in the Snowstorm Jira project. Issues enter this workflow either by being moved from the VWR project, or when a Merge Request issue is created by some Linden scrum team that is ready to merge into the main development viewer.

JIRA-STORM-workflow.png



Normal Workflow Transitions


Open → Start Progress → In Progress (assignee only)
When a developer picks a task to work on from the Sprint List, they Assign the task to themselves and execute this transition to show that work has begun.
In Progress → Ready For Review → Reviewing (assignee only)
When a developer has finished work, they execute this transition, setting:
Reviewing → Add Approval → Reviewing
When each review is complete, the reviewer (normally a Linden) executes this transition, checking either Product Owner or Code Review in the Approvals field.
When both are checked, the last reviewer should execute the Merge transition.
Reviewing → Merge → Approved
At this point, the issue should have satisfied all of the Readiness Criteria. This transition moves the issue to the Snowstorm Integration Queue (including setting it to Unassigned)
Approved → Integrated → Integration Test
When a Snowstorm Team member takes responsibility for pulling the request, they Assign it to themselves (thus removing it from the queue), and execute the hg steps to pull the change to viewer-development. When that is complete, they execute this transition to indicate that QA should test it (sets Assignee to Unassigned).
Integration Test → Pass QA → Passed QA
When a QA tester has confirmed that the issue is fixed in a Development (or later stage - Beta or other release candidate) build, they execute the Passed QA transition.
Passed QA → Close → Closed
When Release posts the final stable release that includes the change for the issue, this transition is executed.




Workflow Transition Exceptions


Open ↔ Needs More Info/Re-Open → Needs More Info
If information from the Reporter or someone else is needed in order to complete the request, these transitions are used to reflect that.
Reviewing → Reject → Open
If either review determines that the change is not ready, this transition is used to return the issue to the developer.
Approved → Integration Failed → Open
If a problem arises when integrating a change, the person that finds the problem executes this transition to return the issue to the developer with a description of the problem to be solved.
Integration Test → Fail QA → Open
Used by QA to indicate that when tested in a Development (or later stage) build, the test failed


Tracking


You can see the current state of the Snowstorm queues:

Reviewing

Development is believed to be complete, and issue is awaiting review and approval.

Integration

Change has been approved for integration into viewer-development

Testing

Change has been integrated and is awaiting QA


These and other Project Snowstorm tracking information are available on the shared "Snowstorm" dashboard in Jira.

Retrieved from "https://wiki.secondlife.com/w/index.php?title=How_To_Submit_A_Viewer_Change&oldid=1157495"