交叉发布在 cynkra 博客上。

一年前，我们 cynkra 的一个小团队向 R Consortium 的 ISC 提交了一个项目提案，该提案获得了批准。我们非常感谢这种支持。在这篇文章中，我们将解释我们项目的动机是什么，我们完成了什么……以及我们希望接下来做什么！

为什么 igraph 需要专门的维护？

igraph R 包的第一个版本于 2006 年在 CRAN 上发布。从那时起，构成 R 包核心的 igraph C 库以及 R 包本身得到了进一步的开发和广泛使用。多年来，R 包也积累了一些文档债务和技术债务，我们希望解决这些问题，以便为 igraph 在未来十年的成功做好准备。这两个方面都有可能简化包的进一步更新。

采用生命周期系统

为了提供更一致的接口，igraph 的部分函数或参数正在缓慢但持续地被弃用。其中一些过去使用自定义解决方案或基础 R 弃用。相比之下，现在所有弃用都通过生命周期包进行。在手册页面上，弃用徽章指示函数或参数的维护状态。

library("igraph")
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union
g <- sample_gnp(10, 0.5)
graph.density(g)
#> Warning: `graph.density()` was deprecated in igraph 2.0.0.
#> ℹ Please use `edge_density()` instead.
#> This warning is displayed once every 8 hours.
#> Call `lifecycle::last_lifecycle_warnings()` to see where this warning was
#> generated.
#> [1] 0.5111111

现在将所有内容都放在“生命周期系统”中意味着界面和文档对用户来说是一致的，而且我们也可以通过搜索生命周期调用来更轻松地随着时间的推移增加弃用级别。最后但并非最不重要的是，所有弃用都列在vignette中。

文档改进

除了生命周期的文档之外，我们还创建并使用了一个自定义 roxygen2 标签，以便从手册页面链接到 C 文档。示例。

更少的错误，更好的错误

我们有意识地努力将错误从基础 R 移植到 cli，同时改进错误的措辞。例如，

stop("invalid value supplied for `weighted' argument, please see docs.")

变成了

cli::cli_abort(c(
  "{.arg weighted} can't be {.obj_type_friendly {weighted}}.",
  i = "See {.help graph_from_biadjacency_matrix}'s manual page."
))

这可以更清楚地说明提供的无效值，并直接链接到手册页面。

我们还修复了一些错误（示例）。

内部工作

我们做了很多重构！其中大部分都集中在测试上，正如之前在本博客上解释的那样：合并一些测试文件以确保 R 脚本和测试文件之间的一致性，重构测试文件以提高可读性和未来的调试，通过删除旧的期望来更新 testthat 的使用。我们还在R/文件夹中工作，例如，我们将嵌入式 lazyeval 的使用替换为 rlang 调用（PR 1，PR 2）。

分享我们的经验

我们分享了我们在 igraph 上的工作经验，一部分是在演讲中，一部分是在各种博客文章中

• useR! 2024 主题演讲 你的代码如何变得生锈，以及你可以做些什么 – 它介绍了我们在 igraph 上的工作。
• 博客文章 使用 {xmlparsedata} 和 {brio} 自动化代码重构 – 我们如何使用脚本而不是手动将一些旧的 testthat 的期望替换为新的期望。
• 博客文章 重构测试文件时我编辑什么 – 一些关于更可读的测试文件的规则，例如将期望更接近它们处理的值。
• 博客文章 使用 treesitter 提取脚本中定义的函数名称 – 我们如何使用脚本来获取我们需要创建的函数列表。
• 博客文章 创建和使用自定义 roxygen2 标签 – 我们如何创建一个自定义 roxygen2 标签以便从手册页面链接到 C 文档。
• 博客文章 覆盖和修改，R 包开发的一些技巧 – 我们如何添加新测试。
• 博客文章 在 R 包中组织测试 – 我们为什么以及如何改进 igraph 中的测试组织。

结论

我们为 igraph 代码库中取得的进展感到自豪，但我们不想止步于此！特别是，我们真的希望在未解决的问题上做更多的工作，以改善问题跟踪器的状态，并确保更容易的未来分类；更好地描述和执行 C 库和 R 库之间的范围差异；并使文档更完整和更清晰。