mrtk_developmentreleases/2.0.0releases/2.1.0releases/2.2.0
  • 指南
  • API 文档
  • 指南
  • Contributing
  • Breaking Changes

    Show / Hide Table of Contents
    • MRTK入门
      • 发布说明
      • MRTK包内容
      • 从早期版本更新
      • 从HTK更新
      • 生成和部署MRTK
      • NuGet包
      • MRTK配置对话框
      • 开始使用 MRTK和XR SDK
      • 性能
      • 全息图稳定
      • 在大型项目中使用MRTK
    • 架构
      • 概述
      • 框架和运行时
      • 输入系统
        • 术语
        • 核心系统
        • Controllers, pointers, and focus
      • 系统,扩展服务和 data providers
    • 功能概述
      • 边界系统 Boundary System
        • 边界系统概述
        • 配置边界可视化
      • 相机系统 Camera System
        • 相机系统概述
        • Camera Settings Providers
          • Windows 混合现实相机设置
          • Unity AR相机设置[实验性]
          • 创建camera settings provider
      • 跨平台支持
        • 为iOS和Android配置MRTK
      • 检测平台能力
      • 诊断系统 Diagnostics System
        • 诊断系统概述
        • 配置诊断系统
        • 使用可视化分析器
      • 扩展服务 Extension Services
        • 扩展服务创建向导
        • 场景过渡服务概述
      • 输入系统 Input System
        • 输入概览
        • 输入动作 Input Actions
        • 输入事件 Input Events
        • Input Providers
          • Input Providers 概述
          • 创建一个 input data provider
        • 控制器 Controllers
        • 眼动跟踪 Eyes
          • 概述
          • 入门
          • 通过代码访问数据
          • 验证跟踪校准 Validate Tracking Calibration
        • 凝视 Gaze
        • 手势 Gestures
        • 手部 Hands
        • 如何添加近距离交互 Near Interaction
        • 编辑器内输入模拟 In-Editor Input Simulation
        • 指针 Pointers
        • 语音输入 Voice Input
          • 语音转录 Dictation
          • 语音(命令和控制) Speech
      • 多场景系统 Multi Scene System
        • 多场景系统概述
        • 场景类型 Scene Types
        • 内容场景加载 Content Scene Loading
        • 监测内容加载 Monitoring Content Loading
        • 光照场景操作 Lighting Scene Operations
      • 打包 Packaging
        • MRTK包 MRTK Packages
        • MRTK模块化 MRTK Modularization
      • 配置文件 Profiles
        • 配置文件概述
        • 配置指南 Configuration Guide
      • 渲染 Rendering
        • 材质实例概述 Material Instance Overview
        • Shaders
          • MRTK标准着色器 MRTK Standard Shader
      • 服务 Services
        • 什么是混合现实特性
        • 什么是 MixedRealityServiceRegistry 和IMixedRealityServiceRegistrar
        • 扩展服务 Extension services
      • 空间感知系统 Spatial Awareness System
        • 空间感知概述
        • Spatial Observers
          • 为设备配置 Observers
          • 为Editor配置 Observers
          • 通过代码控制 Observers
          • 创建自定义 Observer
      • 传送系统概述 Teleport System Overview
      • 工具
        • Dependency Window
        • Extension Service Creation Wizard
        • Holographic Remoting
        • Input Animation Recording
          • Input Animation File Format Specification
        • Optimize Window
        • Runtime tools
          • Controller Mapping tool
      • UX 构建模块
        • 工具箱窗口 Toolbox Window
        • 按钮 Button
        • 边界框 Bounding Box
        • 对象操纵器 Object Manipulator
        • Manipulation Handler [废弃]
        • Slate
        • 系统键盘 System Keyboard
        • 可交互的 Interactable
        • Solvers
          • 点击放置 Tap to Place
        • 对象集合 Object Collection
        • 提示工具条 Tooltips
        • 滑动条 Slider
        • 手部菜单 Hand Menu
        • 近处菜单 Near Menu
        • 应用程序栏 App Bar
        • 指尖可视化 Fingertip Visualization
        • 进度指示器 Progress Indicator
        • 对话框 Dialog [实验性]
        • 手势教学 Hand Coach [实验性]
        • 可滚动对象集合 Scrolling Object Collection [实验性]
        • 脉冲着色器 Pulse Shader [实验性]
        • 停靠控件 Dock Control [实验性]
        • HoloLens键盘助手 [实验性]
      • 示例场景
        • 示例中心
        • 手势交互示例场景
        • 眼动跟踪示例场景
    • Contributing
      • Contributing Overview
      • Coding Guidelines
      • Writing and Running Tests
      • Writing Documentation
      • Pull Requests
      • Experimental Features
      • Breaking Changes
      • How to use DocFX
    • Planning
      • Roadmap
    • Notice
    • Authors

    Breaking changes

    Consumers of the MRTK depend on having a stable release-to-release API surface, so that they can take updates to the MRTK without having large breaking changes each time.

    This page describes our current policy regarding breaking changes in the MRTK, along with some longer term goals around how we can better manage the tradeoff between keeping breaking changes low and being able to make the right long term technical changes to the code.

    What is a breaking change?

    A change is a breaking change if it satisfies any of the conditions in the List A AND satisfies all of the conditions in list B

    List A

    • The addition, removal, or update of any member or function of any interface (or removal/rename of the entire interface).
    • The removal, update (changing type/definition, making private or internal) of any protected or public member or function of class. (or removal/rename of the entire class).
    • The change in the order of events fired by a class.
    • The rename of any private SerializedField (without a corresponding FormerlySerializedAs tag) or public property on a ScriptableObject (especially changes to profiles).
    • Changing the type of a field on a ScriptableObject (especially changes to profiles).
    • Updates to the namespace or asmdefs of any class or interface.
    • Removal of any prefab or removal of a script on the top level object of a prefab.

    List B

    • The asset in question is in the foundation package (i.e. it's in one of the following folders):

      • MRTK/Core
      • MRTK/Providers/
      • MRTK/Services/
      • MRTK/SDK/
      • MRTK/Extensions
    • The asset in question does not belong to the experimental namespace.

    Important

    Any asset that sits in the examples package (i.e. part of the MRTK/Examples/ folder) is subject to change at any time, as assets there are designed to be copied and viewed by consumers as 'reference implementations' but are not part of the core set of APIs and assets. Assets in the experimental namespace (or more generally, features labelled as experimental) are ones that get published before all due diligence has been done (i.e. tests, UX iteration, documentation) and is published early to get feedback sooner. However, because they don't have tests and documentation, and because we likely haven't nailed down all of the interactions and designs, we publish them in a state where the public should assume that they can and will change (i.e. be modified, completely removed, etc).

    See Experimental features for more information.

    As the surface area for breaking changes is very large, it's important to note that having an absolute rule that says "no breaking changes" would be impossible - there may be issues that can only be fixed in a sane way by having a breaking change. To put another way, the only way we could really have "no breaking changes" is to have no changes at all.

    Our standing policy is to avoid making breaking changes if possible, and only do so if the change would accrue significant customer or framework long term value.

    What to do about breaking changes

    If it is possible to accomplish something without a breaking change and without compromising the long term structure and viability of the feature, don't do the breaking change. If there is no other way, the current policy is to evaluate each individual breaking change, to understand if the benefit from taking the change outweighs the cost to the consumer of absorbing the change. Debate about what is worth doing and what isn't will generally take place on the PR or issue discussion itself.

    What can happen here falls into several buckets:

    The breaking change adds value but could be written in a way that isn't breaking

    For example, this PR added a new feature that was initially written in a way that was breaking - it modified an existing interface - but was then rewritten where the feature was broken out as its own interface. This is generally the best possible outcome. Do not try to force a change into a non-breaking form if doing so would compromise the long term viability or structure of the feature.

    The breaking change adds sufficient value to the customer that it's worth doing

    Document what the breaking changes are and provide the best possible mitigation (i.e. prescriptive steps on how to migrate, or better yet tooling that will automatically migrate for the customer). Each release may contain a small amount of changes that are breaking - these should always be documented in docs as was done in this PR. If there already is a 2.x.x→2.x+1.x+1 migration guide, then add instructions or tooling to that doc. If it doesn't exist, create it.

    The breaking change adds value but the customer pain would be too high

    Not all types of breaking changes are created equal - some are significantly more painful that others, based on our experience and based on customer experiences. For example, changes to interfaces may be painful, but if the breaking change is one in which a customer is unlikely to have extended/implemented in the past (the diagnostic visualization system, for example), then the actual cost is probably low to nothing. However, if the change is the type of a field on a ScriptableObject (for example, on one of the core profiles of the MRTK), this is likely to cause massive customer pain. Customers have already cloned the default profile, merging/updating profiles can be extremely hard to do manually (i.e. via a text editor during merge time), and re-copying the default profile and reconfiguring everything by hand is extremely likely to lead to hard to debug regressions.

    These changes we have to put back onto the shelf until a branch exists that will allow significantly breaking changes (along with significant value that will give customers a reason to upgrade). Such a branch doesn't currently exist. In our future iteration planning meetings, we will review the set of changes/issues that were 'too breaking' to see if we reached a critical mass to make it reasonable to pursue a set of changes all at once. Note that it's dangerous to spin up a "everything is allowed" branch without due diligence being done because of the limited engineering resources we have, and the fact that we'd have to split testing and validation across those two. There needs to be a clear purpose and well-communicated start and end date of such a branch when it exists.

    Long term management of breaking changes

    In the long term, we should seek to reduce the scope of what is a breaking change by increasing the set of conditions in List B. Going forward the set of things in List A will always technically be breaking for the set of files and assets that we deem to be in the "public API surface." The way that we can get a little more freedom for iteration (i.e. changing up the internal implementation details, allowing for easier refactoring and sharing of code between multiple classes, etc) is to be more explicit about which portions of the code are official surface, rather than implementation detail.

    One thing we've already done is introduce the concept of an "experimental" feature (it belongs in the experimental namespace, it may not have tests/documentation, and is publicly proclaimed to exist but may be removed and updated without warning). This has given has freedom to add new features sooner to get earlier feedback, but not be immediately tied to its API surface (because we may not have fully thought out the API surface).

    Other examples of things that could help in the future

    • Usage of the internal keyword. This would allow for us to have shared code within our own assemblies (for reducing code duplication) without making things public to external consumers.
    • Creation of an "internal" namespace (i.e. Microsoft.MixedReality.Toolkit.Internal.Utilities), where we publicly document that anything contained within that internal namespace is subject to change at anytime and could be removed, etc. This is similar to how C++ header libraries will make use of ::internal namespaces to hide their implementation details.
    • Improve this Doc
    In This Article
    • What is a breaking change?
      • List A
      • List B
    • What to do about breaking changes
      • The breaking change adds value but could be written in a way that isn't breaking
      • The breaking change adds sufficient value to the customer that it's worth doing
      • The breaking change adds value but the customer pain would be too high
    • Long term management of breaking changes
      • Other examples of things that could help in the future
    Back to top Generated by DocFX