弃用功能指南

关于弃用

在软件开发的正常过程中，一个功能、方法或其他对象可能会被删除。以下是一些指导方针，可确保此过程对用户的干扰最小。

反对什么

任何不再使用的函数、方法或数据。

何时遵循这些指导方针

如果您在包的devel分支中引入了一个函数，然后很快决定不使用它，那么您可以在不遵循这些原则的情况下简单地删除该函数。devel分支是不稳定的，会在没有通知的情况下受到API变化的影响(尽管你可能会决定通过Bioconductor支持网站)。

然而，如果一个功能已经存在于至少一个Bioconductor的发布版本中，则必须遵循这些指南。

如何反对

删除一个函数的整个过程需要三个发布周期(18个月)。

步骤1:弃用函数

当您第一次决定删除一个函数时，应该在devel分支中将其标记为deprecated。通过调用.Deprecated ()内部函数。要做到这一点，您必须提供一个替换函数，该函数应该用于替换旧函数。例子:

myOldFunc <- function() {.Deprecated("myNewFunc") ##使用新函数，或myOldFunc的其余部分}

这将导致每当用户调用时发出警告myOldFunc ()。看到?。弃用为更多的信息。

在旧函数的手册页中指出它已被弃用，并建议使用替代函数。确保在手册页示例或小插图代码块中没有调用旧函数;R CMD检查应该报告这个。

提供这些函数只是为了与旧版本的\ squte {MyPkg}兼容，将在下一个版本中停用。以下函数已弃用并将被禁用;使用下面所示的替换:\itemize{\item{myOldFunc: \code{\link{newFunc}}}}}

步骤2:将函数标记为defunct

在下一个发布周期中，当你的函数被弃用后，它必须在devel分支中失效。这意味着对旧函数的调用将返回一个信息性错误，但不会运行任何附加代码。例子:

myOldFunc <- function() {.Defunct("myNewFunc")}

看到?已经为更多的信息。

删除失效函数的文档，并添加如下的帮助文档:

这些函数是失效的，不再可用。} \details{失效函数是:\code{myOldFunc}}

步骤3:删除功能

在下一个发布周期中，当函数被标记为defunct后，将其从包R代码和devel分支中的NAMESPACE中完全删除。还要删除记录该函数的任何手册页内容。

保留上一步中的手册页，以便

帮助(“MyPkg-defunct”)

仍然显示了失效函数及其适当的替代函数的列表。