• Home
  • Categories
  • WIKI
  • LANGUAGE: en
    • [Feature Requests & Feedback] [Bug / 建议] Treeland Protocols协议发生破坏性变更时未bump version
    deepin 25 486 views · 6 replies ·
    Tofloor
    poster avatar
    CharOfString
    deepin
    2026-10-12 10:35
    Author

    GH Conversation: https://github.com/orgs/linuxdeepin/discussions/13826

    目前，treeland-protocols协议包内部分协议存在协议XML修改（导致协议签名变更）但没有bump协议版本的问题。

    对于Wayland而言，协议的 version 是client与WM协商可用功能的唯一凭证，应用破坏性变更但不bump版本给正在适配改协议的第三方合成器（以及其跨发行版支持）带来了严重兼容性灾难。

    例如：

    0.5.9（提交 8576b9c，2026-06-16）中删除了 get_wallpaper_context请求和 treeland_personalization_wallpaper_context_v1接口，理由是该功能已迁移至 xdg-desktop-portal。这次删除没有bump协议版本号——manager接口前后都是version="2"，接口名也没变，提交信息写的也有Influence: Broken change。

    如果合成器广播 treeland_personalization_wallpaper_context_v1，则所有DTK5/6程序都会尝试走这个协议，以下两种情况会导致协议/实现签名/opcode mismatch导致所有DTK5/6程序拒绝启动：

    1. WM开发时参考了 0.5.8包，广播了来自 0.5.8的协议，但实际编译/runtime的环境是 0.5.9
    2. WM开发时参考了 0.5.9包，广播了来自 0.5.9的协议，但实际编译/runtime的环境是 0.5.8

    如果WM还要适配多发行版，各发行版仓库中的 treeland-protocols版本不同（无法通过简单地vendor最新版本的XML与实现解决 必须为每个版本单独实现），这会导致兼容性灾难...

    建议

    • 在协议变更时更新协议版本号
    • 废弃协议中接口时使用depreciate而不是简单地删除
    Reply Favorite View the author
    All Replies
    avatar
    CharOfString
    deepin
    2026-10-12 10:38
    #1

    这对任何一个想支持多发行版的同时支持 treeland_personalization_wallpaper_context_v1协议的三方合成器都是灾难性的，后果就是OPCode MISMATCH，导致所有DTK5/6程序不启动，报无法连接到wayland

    Reply View the author
    avatar
    神末shenmo
    deepin
    Spark-App
    Q&A Team
    2026-10-12 15:32
    #2

    强烈支持！这玩意给我session炸飞了

    Reply View the author
    avatar
    CharOfString
    deepin
    2026-10-12 16:51
    #3
    神末shenmo：

    强烈支持！这玩意给我session炸飞了

    我自己的GXWM会话也炸飞了，要不是夏天的时候我们写了一段兜底代码我们到现在都进不去Wayland会话

    Reply View the author
    avatar
    zzxyb
    deepin
    Community Developer
    2026-10-13 10:53
    #4

    你好，我是 8576b9c 的作者。

    首先，对于提交 8576b9c 给您这边带来的影响和额外适配工作，我深表歉意，也感谢您对 Treeland 协议设计提出的建议。

    此次调整主要是因为原有的 treeland_personalization_wallpaper_context_v1 协议在设计上存在 安全隐患，同时在功能扩展和职责划分方面也存在一定局限性。出于安全性、可维护性以及长期演进的考虑，我们对壁纸相关协议进行了重新设计。

    新的壁纸协议主要包含以下两个部分：

    相比原有设计，新协议主要在以下方面进行了改进：

    1. 更完善的壁纸功能支持：同时支持静态壁纸和动态壁纸，为后续功能扩展提供更灵活的基础。
    2. 更清晰的协议职责划分：将壁纸设置、状态监听以及 Shell 相关能力进行合理拆分，避免将多个职责独立的 Interface 集中定义在同一个 XML 文件中。
    3. 更好的可扩展性与可维护性：通过相对独立的协议设计，降低功能间的耦合程度，便于后续维护和迭代。

    不过，此次设计调整不可避免地导致原有的 treeland_personalization_wallpaper_context_v1 协议被废弃，并产生了不兼容变更。

    因此，我们在 PR #72 中明确将此次修改标记为 Breaking Change，希望依赖该协议的客户端能够在重新编译时及时发现不兼容问题，并根据新的协议设计完成适配。

    另外，为了尽可能避免类似的兼容性问题，建议后续使用 treeland-protocols 时优先依赖上游维护的协议定义，而不是自行 Fork 或维护独立的 XML 副本，以便及时感知协议的更新与变化。

    关于您提出的 Deprecated（弃用标记） 建议，我们已经在最新的设计中予以采纳。后续 Treeland 的协议开发也会更加重视接口职责的独立性、规范化管理，以及协议演进过程中的兼容性保障。

    treeland-protocols 项目目前还处于alpha状态，我们在完善过程中可能会有持续的改动，都是在让它变的更好。

    Reply View the author
    avatar
    zccrs
    deepin
    2026-10-13 11:30
    #5
    zzxyb：

    你好，我是 8576b9c 的作者。

    首先，对于提交 8576b9c 给您这边带来的影响和额外适配工作，我深表歉意，也感谢您对 Treeland 协议设计提出的建议。

    此次调整主要是因为原有的 treeland_personalization_wallpaper_context_v1 协议在设计上存在 安全隐患，同时在功能扩展和职责划分方面也存在一定局限性。出于安全性、可维护性以及长期演进的考虑，我们对壁纸相关协议进行了重新设计。

    新的壁纸协议主要包含以下两个部分：

    相比原有设计，新协议主要在以下方面进行了改进：

    1. 更完善的壁纸功能支持：同时支持静态壁纸和动态壁纸，为后续功能扩展提供更灵活的基础。
    2. 更清晰的协议职责划分：将壁纸设置、状态监听以及 Shell 相关能力进行合理拆分，避免将多个职责独立的 Interface 集中定义在同一个 XML 文件中。
    3. 更好的可扩展性与可维护性：通过相对独立的协议设计，降低功能间的耦合程度，便于后续维护和迭代。

    不过，此次设计调整不可避免地导致原有的 treeland_personalization_wallpaper_context_v1 协议被废弃，并产生了不兼容变更。

    因此，我们在 PR #72 中明确将此次修改标记为 Breaking Change，希望依赖该协议的客户端能够在重新编译时及时发现不兼容问题，并根据新的协议设计完成适配。

    另外，为了尽可能避免类似的兼容性问题，建议后续使用 treeland-protocols 时优先依赖上游维护的协议定义，而不是自行 Fork 或维护独立的 XML 副本，以便及时感知协议的更新与变化。

    关于您提出的 Deprecated（弃用标记） 建议，我们已经在最新的设计中予以采纳。后续 Treeland 的协议开发也会更加重视接口职责的独立性、规范化管理，以及协议演进过程中的兼容性保障。

    treeland-protocols 项目目前还处于alpha状态，我们在完善过程中可能会有持续的改动，都是在让它变的更好。

    这个回复也太官方了。

    @CharOfString @神末shenmo 抱歉啊，Treeland 这些协议设计时比较仓促，当时就想过肯定会重构，所以专门在协议里加了个警告，就怕被人用到了，没想到还是影响到了。几个月前修改过一次（当时没注意到外面可能有人在依赖这个协议，加上之前就没打算对这个版本保持兼容，所以直接就改了，没有改协议名，也没有考虑兼容性问题）。为了减少发生破坏性变化的次数，所以9 月份和 10 月在做全量的协议梳理，不少协议都做了修改，不过这次修改暂时保留了旧协议文件，以改名或加新协议的方式做的重新设计。但旧协议过俩月也会删掉，不过这次是一个集中性的修改，做完后后续的改动会跟上游的协议一样，会按惯例维护它们，不会再轻易改动。

    Reply View the author
    avatar
    神末shenmo
    deepin
    Spark-App
    Q&A Team
    2026-10-13 19:19
    #6
    zccrs：

    这个回复也太官方了。

    @CharOfString @神末shenmo 抱歉啊，Treeland 这些协议设计时比较仓促，当时就想过肯定会重构，所以专门在协议里加了个警告，就怕被人用到了，没想到还是影响到了。几个月前修改过一次（当时没注意到外面可能有人在依赖这个协议，加上之前就没打算对这个版本保持兼容，所以直接就改了，没有改协议名，也没有考虑兼容性问题）。为了减少发生破坏性变化的次数，所以9 月份和 10 月在做全量的协议梳理，不少协议都做了修改，不过这次修改暂时保留了旧协议文件，以改名或加新协议的方式做的重新设计。但旧协议过俩月也会删掉，不过这次是一个集中性的修改，做完后后续的改动会跟上游的协议一样，会按惯例维护它们，不会再轻易改动。

    非常感谢回复，作为 deepin 的下游项目，也衷心希望 deepin 越来越好

    cc @CharOfString
    目前内测炸 wl session 的问题大概需要做什么操作来解决？我发一下

    Reply View the author