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

时间:2009-02-17 13:57:41

标签: git project-management backwards-compatibility incompatibility

有时候,当改进远远超过缺点时,你需要引入向后不兼容的变化。可以轻松切换到旧行为,但用户必须了解此类更改。

因此问题是:如何宣布将来向FLOSS(开源)项目进行后向不兼容的更改,以便用户可以为它们做好准备,并改变其使用方式,或者配置程序使用旧的行为。

因为它是OSS项目,所以它由各种发行版独立打包,并且可以在没有用户干预的情况下自动升级。然后,向后不兼容的更改可能会破坏某些工作流程(例如第三方脚本)。

目前考虑(和使用)的途径:

  • 项目邮件列表
  • 项目主页
  • 发行说明(第一次警告,然后公告)
  • 维护者的博客

编辑1:此(后向不兼容)更改将在某些主要版本中发生。

所有更改都是关于添加安全措施(拒绝可能彻底混淆新手用户的命令),或将默认值更改为更合理的值。

编辑2:在过渡期间,默认配置(意图更改为默认拒绝/拒绝)更改为警告,并说明如何转弯一个警告,它也可以防止默认行为的向后不兼容的变化。

但如果是自动化系统可能无济于事......


有问题的项目是Git,分布式版本控制系统;
请参阅Giving early warning to users上的gitster's journal(Junio C Hamano博客)

5 个答案:

答案 0 :(得分:9)

  • 更改版本号的主要内容
  • 通过您掌握的所有途径宣布
  • 在自述文件中添加重要声明
  • 如果需要更改数据库或需要其他更改,请添加在旧旧之间进行转换的代码
  • 添加检测使用折旧方法,数据存储等的代码,并在执行破坏性更改之前提醒用户
  • 在主要Q / A网站上询问相关常见问题解答类型问题,以便当有人查询时,使用简单搜索即可立即明白答案

但主要版本号是主要目标 - 人们期望1.x到2.x过渡会导致问题,并且在升级时会更加小心。

- 亚当

答案 1 :(得分:2)

你已经得到了很好的答案。但是迁移我自己的心态对我来说是最大的问题,特别是当被弃用的功能存在于我的肌肉记忆中时。忘却比学习更难。

当我实际使用要更改的命令时,获取有关不兼容的的警告特别有用,尤其是在默认值更改时。类似的东西:

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

答案 2 :(得分:1)

我可以去RSS(如果存在),Twitter(如果存在),邮件列表(邮件至少3次,因为更新正在关闭),主页(使它非常对比,所以很容易看到)和博客, 当然。发行说明几乎没有读过,所以把它作为最后一点信息。

(我把它作为第一个答案发布,但没有显示)

答案 3 :(得分:1)

以上所有加号。

如果你有改变:

非破坏性命令的确切语法将变为破坏性命令

我认为没有选择,只是进行更改而不是更多中断以使旧命令完全无效,这样如果用户升级并尝试(或很可能是脚本尝试)旧样式命令,它就会终止在stderr上有描述性错误消息。 使用stderr对命令发出警告消息,并且具有非破坏性的微妙(或不那么微妙)的变化也是一个好主意。 破坏性的定义在源存储库中稍微复杂一些

对于简单的弃用方法使用stderr警告通常是好的,但有些人会抱怨它打破了他们(写得不好)的脚本。在这些情况下,静默弃用版本(所有非侵入性弃用形式)随后发布口头(stderr警告),然后(见下文)发布一个非功能性但现在的版本,然后是完全删除。最后一个非功能版本将在很大程度上依赖于相关项目,因为它可能比它的价值更麻烦,特别是那些表现良好并且不断更新已弃用功能的用户。

由于您引用的具体更改是删除内置的ins,这应该没问题我可能不会在非功能模式下使用内置函数进行一次发布,但我不知道该项目是否足够好说得肯定。

注意代码而不是脚本级别的更改,在许多现代语言中,可以在带有属性/注释的方法存根中保留它们,这将完全隐藏智能感知并拒绝对它们进行编译。这使得它们的存在(如果使用了一个简单的例外)是一种更好的方法,可以找出你不能使用它们而不是运行时MissingMethodException等等。

答案 4 :(得分:-1)

只需0.02美元。现代开发环境(特别是.NET)提供了向开发人员报告某些API被声明为过时/弃用的方法,并将在未来版本中删除。 Microsoft C / C ++编译器具有#pragma deprecated

如果您的环境不支持此功能,请依靠versioning提供compat反馈。