Difference between revisions of "How To Submit A Viewer Change"

Latest revision as of 14:16, 6 July 2017

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.

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.
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 create a fork of the viewer-release repository and commit the changes to that fork, then fill in the URL for that fork in the "Repository Fixed In" field of a Jira issue.
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.
The Project repository must have merged in the latest changes from viewer-release.
The results must be validated by building viewers for all platforms and doing at least minimal viewer testing.
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, submit a Merge Request as detailed on the (internal) Viewer Release Workflow page.

Open Source Submissions

Open source contributors should be working on issues that are already in the Snowstorm Jira project. Before submitting (or even doing work) it is best to have first made a proposal and had it approved as described on the Snowstorm Project page (any submission will go through this review anyway, and not doing it at the outset may mean doing work that either isn't accepted at all or will have to be significantly modified).

The following describes the workflow for issues in the Snowstorm Jira project. Issues enter this workflow either by being moved from the BUG project, or when a proposal outside jira is accepted and a STORM issue created directly. The same workflow is used for the Open Development Jira project, but issues there are only for changes to the process of building the viewer, not for changes to how the viewer works.

Open this link in a new window to see the workflow diagram.

Note: You can see the workflow, with the current step for an issue highlighted, by clicking on the '(View Workflow)' link next to its Status in the issue display.

Open: An issue that is ready to be worked on; it may or may not be Assigned to someone. When someone takes responsibility for it, the issue should be Assigned to them and they should execute the Start Progress transition to move the issue to show that work has begun (as a side effect, this Assigns the issue to that user).

→ Start Progress →

In Progress

When a developer has finished work, they:

set the Branch/Repo Fixed In and Changeset/Revision ID fields to point to a public mercurial repository containing the change
set the Code Review field to the URL of the Diff display in the Bitbucket "Compare" display.
execute the transition to indicate that it is ready:

→ Ready For Review (assignee only) →

Code Review: Reviews may come from other open source developers and/or Lindens. The developer should respond to issues raised in the review; when the code passes code review, Oz will send it to the QA team (sometimes bundled with other issues in a test build) and transition the issue

→ Pass Code Review →

Team QA: Linden internal QA team will test the issue using the test plan in the issue and the existing regression tests, and if it passes,

→ Pass Team QA →

Product Review: This is the final acceptance review by the Linden Product Team; when it has been approved for integration

→ Approved →

Integration Ready: which indicates that it is eligible to be merged to viewer-development; when that has happened

→ Integrated →

Integrated: where it will again be tested for problems that may have arisen due interactions with other new development

→ Pass IQA →

Passed IQA: where it will remain until the next release is created from viewer-development; the final transition

→ Close →

Closed: because it's in the Viewer!

of course, each of these steps also include the possibility of some failure, which will transition the issue back to Open for further work, and then the cycle begins again.

Tracking

You can see the current state of the Snowstorm issues on the shared "Snowstorm" dashboard in Jira.

@@ Line 27: / Line 27: @@
 # '''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.
+#: The strongly preferred way to review code is to create a fork of the [https://bitbucket.org/lindenlab/viewer-release viewer-release] repository and commit the changes to that fork, then fill in the URL for that fork in the &quot;Repository Fixed In&quot; field of a Jira issue.
 # '''There must be a test plan'''
 #: The test plan must describe in detail how Integration QA can validate the modified behavior.
@@ Line 33: / Line 33: @@
 #:* 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.
-# '''The Project repository must have merged in the latest changes from Development.'''
+# '''The Project repository must have merged in the latest changes from viewer-release.'''
 #: The results must be validated by building viewers for all platforms and doing at least minimal viewer testing.
-# '''There must be a [http://lecs.opensource.secondlife.com/SLVcontribution_agmt.pdf Contribution Agreement] on file from each contributor to the change that is not a Linden employee or contractor.'''
+# '''There must be a [http://lecs-opensource.secondlife.com/SLVcontribution_agmt.pdf 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 <code>doc/contributions.txt</code>
 #* If you already have one or more entries in <code>contributions.txt</code>, add new ones at the appropriate positions (sorting yours, if desired).
@@ Line 44: / Line 44: @@
 ===Linden Submissions===
 <br />
-When the code has met all of the above-stated Readiness Criteria, you will need to 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, in detail, below.
+''After'' the code has met all of the above-stated Readiness Criteria, submit a Merge Request as detailed on the (internal) [https://wiki.lindenlab.com/wiki/Viewer_Release_Workflow#Submitting_a_Merge_Request Viewer Release Workflow page].
-<br /><br />
-<span style="font-size:14px">'''Clone the Merge Request template'''</span>
-#  Login to your Jira account
-#  Go to the [https://jira.secondlife.com/browse/STORM-1348 Merge Request template issue]
-#*  From the '''More Actions''' drop-down, select '''Clone'''
-#*  Enter a <u>meaningful</u> Merge Request Summary (e.g. 'Merge Soft-Body Physics project to viewer-development')
-<br />
-<span style="font-size:14px">'''Edit your Merge Request'''</span>
-#  Click '''Edit'''
-#  Change '''Reporter''' to your Jira user name
-#  In the '''Branch/Repo Fixed In''' field, replace ''<project repository>'' with the full path of your project repository
-#  Update the '''Description''' field by completing the '''bolded''' sections
-#*  Under '''Description of Change(s)''', provide a brief description of the feature, functionality, or fixes to be integrated
-#*  Under '''Potential Risks''', describe the general complexity of the change (i.e. two-line change versus hundreds of files), the areas of the viewer impacted by the change(s), and your best estimate of the potential risk to the stability of the viewer (e.g. High, Medium, Low)
-#*  Under '''Steps Taken to Mitigate Risks''', mention any efforts undertaken to minimize the potential risks of introducing the change(s)
-#*  Under '''Primary Jira(s) Addressed''', follow the instructions in the section and list only the most prominent Jiras (this is particularly important when requesting the integration of a long-term project, with a large number of individual Jiras)
-#*  Under '''Known Issues''', please follow the instructions and list any still Unresolved '''Major''' or '''Severe''' bugs known to exist in the project code
-#*  From the '''More Actions''' drop-down, select '''Link''' and link <u>all</u> Jiras addressed by the request (for very large, long-term projects, linking the issues listed in the '''Primary Jira(s) Addressed''' section should be sufficient - as long as the majority of the issues addressed by the merge are covered by those Jiras)
-#*  Save your changes
-<br />
-'''Note that, by default, all issues in the Snowstorm Jira project are visible to the public.'''
-<br /><br />
-Merge Requests are created with a Status of '''Approved'''.  Please do '''not''' change the Status or Assign the issue to anyone.  Snowstorm team members regularly monitor incoming Merge Requests and one of them will pick up the issue and do the pull.  The majority of Merge Requests are resolved within 24 hours of creation, but if you would like to confirm that someone has seen the request, just ping in #snowstorm.
-<br /><br />
-Linden developers ''may'' request write access to the Development branch and push directly, but this practice is discouraged, as it makes other integrations within the Snowstorm team more difficult.  Requests for write access to the viewer-development repo should be sent to Oz, via email, with the name of your account at bitbucket.org.  Please note that write access will be temporary, and will be revoked as soon as the requested merge has been successfully completed.
-<br /><br />
-<br />
-----
 ===Open Source Submissions===
-<br />
-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
+Open source contributors should be working on issues that are already in the [http://jira.secondlife.com/browse/STORM Snowstorm Jira project].  Before submitting (or even doing work) it is best to have first made a proposal and had it approved as described on the [[Snowstorm Project]] page (any submission will go through this review anyway, and not doing it at the outset may mean doing work that either isn't accepted at all or will have to be significantly modified).
-: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
+The following describes the workflow for issues in the [http://jira.secondlife.com/browse/STORM Snowstorm Jira project].  Issues enter this workflow either by being moved from the BUG project, or when a proposal outside jira is accepted and a STORM issue created directly. The same workflow is used for the [http://jira.secondlife.com/browse/OPEN Open Development Jira project], but issues there are ''only'' for changes to the process of building the viewer, not for changes to how the viewer works.
-:This should be the URL of a review of that same change posted at codereview.secondlife.com (see [[Code Review Tool]])
-<br />
-== Snowstorm Workflow Detail ==
+[https://jira.secondlife.com/plugins/servlet/workflow/thumbnail/getThumbnail?workflowName=Team%20Development%20Workflow&stepId=10&width=full&height=full| Open this link in a new window to see the workflow diagram].
-<br />
-The sections below describe the workflow for issues in the [http://jira.secondlife.com/browse/STORM 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.
-[[Image:JIRA-STORM-workflow.png|right]]
+{{KBnote|You can see the workflow, with the current step for an issue highlighted, by clicking on the '(View Workflow)' link next to its Status in the issue display.}}
-<br />
-<br />
-===Normal Workflow Transitions===
+;Open
-<br />
+:An issue that is ready to be worked on; it may or may not be Assigned to someone.  When someone takes responsibility for it, the issue should be Assigned to them and they should execute the ''Start Progress'' transition to move the issue to show that work has begun (as a side effect, this Assigns the issue to that user).
-;Open  &rarr;  ''Start Progress''  &rarr;  In Progress (''assignee only'')
+&rarr; ''Start Progress'' &rarr;
-: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
-----
+:When a developer has finished work, they:
-;In Progress  &rarr;  ''Ready For Review''  &rarr;  Reviewing (''assignee only'')
+:*set the '''Branch/Repo Fixed In''' and '''Changeset/Revision ID''' fields to point to a public mercurial repository containing the change
-:When a developer has finished work, they execute this transition, setting:
+:*set the '''Code Review''' field to the URL of the Diff display in the Bitbucket &quot;Compare&quot; display.
-:*'''Branch/Repo Fixed In''' and '''Changeset/Revision ID''' fields to point to a public mercurial repository containing the change
+:*execute the transition to indicate that it is ready:
-:*'''Code Review''' to the URL of [[Code_Review_Tool#Post_Code_To_Be_Reviewed|a code review in the Code Review Tool]]
+&rarr; ''Ready For Review'' (''assignee only'') &rarr;
-----
+;Code Review
-;Reviewing  &rarr;  ''Add Approval''  &rarr;  Reviewing
+:Reviews may come from other open source developers and/or Lindens.  The developer should respond to issues raised in the review; when the code passes code review, Oz will send it to the QA team (sometimes bundled with other issues in a test build) and transition the issue
-:When each review is complete, the reviewer (normally a Linden) executes this transition, checking either '''Product Owner''' or '''Code Review''' in the '''Approvals''' field.
+&rarr; ''Pass Code Review'' &rarr;
-:When both are checked, the last reviewer should execute the ''Merge'' transition.
+;Team QA
-----
+:Linden internal QA team will test the issue using the test plan in the issue and the existing regression tests, and if it passes,
-;Reviewing  &rarr;  ''Merge''  &rarr;  Approved
+&rarr; ''Pass Team QA'' &rarr;
-:At this point, the issue should have satisfied all of the [[#Readiness_Criteria|Readiness Criteria]].  This transition moves the issue to the Snowstorm Integration Queue (including setting it to Unassigned)
+;Product Review
-----
+:This is the final acceptance review by the Linden Product Team; when it has been approved for integration
-;Approved  &rarr;  ''Integrated''  &rarr;  Integration Test
+&rarr; ''Approved'' &rarr;
-: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 Ready
-----
+:which indicates that it is eligible to be merged to viewer-development; when that has happened
-;Integration Test  &rarr;  ''Pass QA''  &rarr;  Passed QA
+&rarr; ''Integrated'' &rarr;
-: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.
+;Integrated
-----
+:where it will again be tested for problems that may have arisen due interactions with other new development
-;Passed QA  &rarr;  ''Close''  &rarr;  Closed
+&rarr; ''Pass IQA'' &rarr;
-:When Release posts the final stable release that includes the change for the issue, this transition is executed.
+;Passed IQA
-----
+:where it will remain until the next release is created from viewer-development; the final transition
-<br style='clear: both;'/>
+&rarr; ''Close'' &rarr;
-<br />
+;Closed
-<br />
+:because it's in the Viewer!
-=== Workflow Transition Exceptions ===
+of course, each of these steps also include the possibility of some failure, which will transition the issue back to Open for further work, and then the cycle begins again.
-<br />
-;Open  &harr;  ''Needs More Info/Re-Open''  &rarr;  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  &rarr;  ''Reject''  &rarr;  Open
-:If either review determines that the change is not ready, this transition is used to return the issue to the developer.
-----
-;Approved  &rarr;  ''Integration Failed''  &rarr;  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  &rarr;  ''Fail QA''  &rarr;  Open
-:Used by QA to indicate that when tested in a Development (or later stage) build, the test failed
-<br />
 ==Tracking==
-<br />
-You can see the current state of the Snowstorm queues:
-==== [http://jira.secondlife.com/secure/IssueNavigator.jspa?mode=hide&requestId=13082 Reviewing] ====
-Development is believed to be complete, and issue is awaiting review and approval.
-<br />
-==== [http://jira.secondlife.com/secure/IssueNavigator.jspa?mode=hide&requestId=13064 Integration] ====
-Change has been approved for integration into viewer-development
-<br />
-==== [http://jira.secondlife.com/secure/IssueNavigator.jspa?reset=true&jqlQuery=project+%3D+STORM+AND+status+%3D+Integrated+ORDER+BY+updated+DESC%2C+priority+DESC Testing] ====
-Change has been integrated and is awaiting QA
-<br />
-These and other Project Snowstorm tracking information are available on the shared "Snowstorm" dashboard in Jira.
+You can see the current state of the Snowstorm issues on the shared [https://jira.secondlife.com/secure/Dashboard.jspa?selectPageId=13615 "Snowstorm" dashboard] in Jira.