如何在OSS项目中宣布向后不兼容的变更？

发布于 2024-07-13 08:59:42 字数 936 浏览 4 评论 0原文

有时，当改进远远超过缺点时，您需要引入向后不兼容的更改。可以轻松切换到旧行为，但用户必须意识到此类更改。

因此，问题是：如何宣布未来对 FLOSS（开源）项目的向后不兼容的更改，以便用户可以为此做好准备，并更改其用途，或将程序配置为使用旧行为。

因为它是OSS项目，所以它是由各个发行版独立打包的，并且可以在不需要用户干预的情况下自动升级。然后向后不兼容的更改可能会扰乱某人的工作流程（例如第三方脚本）。

当前考虑（和使用）的途径：

项目邮件列表
项目主页
发行说明（首先警告，然后公告）
维护者博客

编辑1：这种（向后不兼容）更改将在某些主要释放。

所有更改都是关于添加保护措施（拒绝可能彻底迷惑新手用户的命令），或将默认值更改为更合理的值。

编辑2：在过渡期间，默认配置（即更改为默认拒绝/拒绝）更改为警告，并说明如何关闭警告，这也可以防止默认行为发生向后不兼容的更改。

但如果它是自动化系统，可能没有帮助......

有问题的项目是 Git，分布式版本控制系统；
请参阅向用户发出早期警告，网址为gitster 的日记（Junio C Hamano 博客）

原文

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

無處可尋 2024-07-20 08:59:42

更改版本号的主要版本
通过您可以使用的所有途径进行公告
在自述文件中添加突出的公告
如果需要数据库或其他更改，则添加在新旧版本之间进行转换的代码
添加用于检测折旧方法、数据存储等的使用的代码并在执行破坏性更改之前提醒用户
在主要 Q/A 网站上提出相关的常见问题解答类型问题，以便当人们有疑问时，使用简单的搜索即可立即得到明显的答案

但主要版本号是主要目标 - 人们期望 1.x 2.x 过渡会引起问题，升级时要更加小心。

-亚当

回复收藏 0 原文

演多会厌 2024-07-20 08:59:42

关于宣传，你已经有了很好的答案。但迁移我自己的思维方式对我来说是最大的问题，特别是当我的肌肉记忆中已弃用的功能时。忘却比学习更难。

当我实际使用将要更改的命令时，收到有关即将发生的不兼容的警告特别有用，尤其是在默认值发生更改的情况下。就像是：

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.

You've got good answers about getting the word out. But migrating my own mindset is the biggest issue for me, particularly when the deprecated functions are in my muscle memory. Unlearning is harder than learning.

Getting warnings of coming incompatibilites when I'm actually using the commands that are going to change is particularly helpful, especially with changes in defaults. Something like:

 $ git foo  
 Note: git foo currently defaults to HEAD. Starting with
 version 2.0, git foo will instead default to master.

回复收藏 0 原文

诗笺 2024-07-20 08:59:42

当然，我可以选择 RSS（如果存在）、Twitter（如果存在）、邮件列表（更新即将结束时至少发送 3 次邮件）、主页（使其形成鲜明对比，以便易于查看）和博客。发行说明很少被阅读，因此将其作为最后一点信息。

（我将此作为第一个答案发布，但没有出现）

回复收藏 0 原文

深爱不及久伴 2024-07-20 08:59:42

以上全部加上。

如果您进行了以下更改：

非破坏性命令的确切语法将更改为破坏性命令，

我看不到任何选项，只能进行更改更具破坏性，以使旧命令完全无效，以便如果用户升级并尝试（或者很可能是脚本尝试）旧式命令，它会在 stderr 上显示描述性错误消息并终止。
使用 stderr 对具有非破坏性的微妙（或不那么微妙）变化的命令发出警告消息也是一个好主意。
在源存储库上，破坏性的定义有些复杂。

对简单的弃用方法使用 stderr 警告通常是好的，但有些人会抱怨它破坏了他们（写得不好的）脚本。在这些情况下，先进行静默弃用发布（所有非侵入性弃用形式），然后进行口头（stderr 警告）发布，然后可能（见下文）进行非功能性但存在的发布，然后完全删除。最后一个非功能性版本将严重依赖于相关项目，因为它可能带来的麻烦大于其价值，特别是对于那些行为良好并及时了解已弃用功能的用户而言。

由于您引用的具体更改是删除内置插件，这应该没问题，我可能不会在非功能模式下使用内置插件发布一个版本，但我不太了解该项目，无法肯定地说。

请注意，对于代码而不是脚本级别的更改，在许多现代语言中可以保留带有属性/注释的方法存根，这将完全隐藏它们以防止智能感知并拒绝对其进行编译。这使得它们的存在（如果使用则有一个简单的异常）是一种比运行时 MissingMethodException 或其他更好的方式来发现您不能使用它们。