release-post

软件包发布博客文章

按照 Tidyverse 或 Shiny 博客的惯例，撰写专业的 R/Python 软件包发布博客文章。

快速开始

1. 确定博客平台：Tidyverse（tidyverse.org）或 Shiny（shiny.posit.co）
2. 确认软件包是否有 NEWS.md 或变更日志
3. 收集软件包信息：名称、版本、代码仓库（例如“tidyverse/dplyr”）
4. 按照以下工作流程操作
5. 使用 scripts/get_contributors.R 生成致谢名单
6. 参考相应的格式指南进行最后润色

平台选择

此技能支持两个格式要求不同的博客平台：

• Tidyverse 博客（tidyverse.org）

  • 使用 hugodown
  • 主要面向 R 软件包
  • 结构和惯例更为严格
  • 请参阅 references/tidyverse-formatting.md

• Shiny 博客（shiny.posit.co）

  • 使用 Quarto
  • 面向 R 和 Python 软件包
  • 结构更灵活，更注重功能
  • 请参阅 references/shiny-formatting.md

首先，确定文章面向哪个平台，然后遵循通用工作流程并采用相应的平台专属格式。

通用工作流程

以下步骤适用于两个平台。内容指南以 Tidyverse 最佳实践为基础，但可根据需要调整，以适用于 Shiny 文章。

步骤 1：收集信息

收集所需信息：

• 平台：Tidyverse 还是 Shiny 博客？
• 软件包名称和版本：例如“dplyr 1.2.0”或“shiny 1.9.0”
• 代码仓库：采用“所有者/仓库”格式的 GitHub 仓库
• 软件包语言：R 或 Python
• NEWS 内容：阅读软件包的 NEWS.md、CHANGELOG 或 NEWS
• 软件包描述：用一句话概括其核心用途
• 上一个发布标签：用于获取贡献者（可选）
• 特色图片：用于 frontmatter（可选，但推荐）

步骤 2：构建文章结构

按以下顺序创建文章大纲：

1. Frontmatter：平台专属 YAML（参阅格式指南）

2. 标题和开篇：

   • 标题：软件包名称和版本
   • 开篇：发布公告，并用一句话描述软件包
   • 安装：包含安装命令的代码块
   • 概览：简要总结，并链接到完整的发布说明

3. 正文（选择适当的章节）：

   • 迁移指南（如有破坏性变更）——有此内容时始终放在最前面
   • 生命周期变更（弃用、软弃用、停止支持）
   • 功能章节（每项主要功能单独成节，标题应清晰描述内容）
   • 次要改进（项目符号列表）

4. 致谢（适用时）：

   • 使用 scripts/get_contributors.R
   • 格式：“衷心感谢所有帮助实现本次发布的伙伴：”
   • 使用逗号分隔的 GitHub 链接

步骤 3：应用内容指南

遵循 references/content-guidelines.md 中的最佳实践：

• 开篇风格：“我们很[随机选择一个表达兴奋的形容词]地宣布……正式发布。”
• 章节顺序：迁移 → 生命周期 → 功能 → 改进 → 致谢
• 语气：自然、专业、热情而真诚
• 技术准确性：在反引号中使用准确的函数名称
• 关注收益：解释“为什么”，而不只是“是什么”
• 代码示例：内容真实合理、注释充分、格式规范

第 4 步：转换 NEWS 内容

将 NEWS.md 中的要点改写成适合博客的内容：

• 深入研究功能：不要只照搬 NEWS 中的要点；阅读函数文档、查看 PR，了解相关背景
• 补充背景信息：说明这些变更为何重要，而不只是说明变更内容
• 添加完整代码示例：展示包含完整工作流的实际用法，而不只是函数签名
• 先解释概念：对于不熟悉的功能，先说明它是什么、如何工作，再展示代码
• 按主题分组：将相关的 NEWS 条目合并为连贯的章节
• 采用对话式语气：将简短的要点改写为行文流畅的内容
• 链接文档：添加相关文档和资源的链接
• 突出不兼容变更：明确说明迁移路径
• 多语言一致性（仅限 Shiny）：对于 Shiny 博客中的 R+Python 软件包，确保所有示例都在标签页组中同时展示两种语言

第 5 步：应用平台专属格式

对于 Tidyverse 博文，请阅读 references/tidyverse-formatting.md 并按要求处理：

• 使用包含 slug、photo.url、photo.author 的 hugodown frontmatter
• 使用指定的 slug 格式：packagename-x-y-z（用连字符替换点）
• R 代码块使用 r 语言标识符
• 鸣谢始终作为最后一个章节

对于 Shiny 博文，请阅读 references/shiny-formatting.md 并按要求处理：

• 使用带有 YAML 锚点（用于社交媒体）的 Quarto frontmatter
• 标题格式灵活
• 使用标签页组展示 Python/R 或 Express/Core 的不同版本
• 使用平台专属的代码块属性
• 鸣谢可选，视博文类型而定
• 可使用导语段落、提示框和嵌入式媒体

第 6 步：生成鸣谢

运行贡献者脚本：

Rscript scripts/get_contributors.R "owner/repo"

也可以指定上一个版本的起始标签（或上一则发布博文使用的标签）：

Rscript scripts/get_contributors.R "owner/repo" "v1.0.0"

将 Markdown 输出复制到“鸣谢”章节。

第 7 步：审阅并润色

适用于所有平台的检查清单：

• Frontmatter 包含所有必填字段
• 开篇清楚说明软件包的用途
• 包含安装代码块（如适用，需同时提供两种语言）
• 章节组织合理
• 代码示例使用正确的语法高亮
• 函数名使用反引号，并带圆括号：`function()`
• 软件包名称不使用反引号或其他样式
• 语气轻松自然，但不带营销腔
• 不使用最高级词语（“强大”“丰富”“无缝”等）
• 结合背景解释功能，而不只是列出功能
• 展示代码前先解释概念
• 所有示例都展示 R 和 Python 版本（如适用）
• 包含完整发行说明的链接

平台专属检查清单：

Tidyverse：

• Slug 格式为：package-x-y-z（使用连字符，不用点）
• 包含照片 URL 和作者
• “鸣谢”章节是最后一个章节
• 所有贡献者按字母顺序排列

Shiny：

• 使用 YAML 锚点设置描述（&desc、*desc）
• 配置社交媒体卡片（open-graph、twitter-card）
• 使用标签页组或 shinylive 时，指定适当的过滤器
• 使用标签页组展示成对的版本（Python/R、Express/Core）
• 一致使用多语言标签页组（仅限 R+Python 软件包）

参考文档

根据需要加载以下文档以获取详细指导：

内容指南

references/content-guidelines.md —— 所有发布博文通用的最佳实践：

• 博文结构与组织
• 开篇风格与语气
• 章节层级与组织
• 代码示例与格式
• 前后对比模式
• 鸣谢规范

平台特定格式要求

references/tidyverse-formatting.md - Tidyverse 博客要求：

• hugodown 前置内容结构
• Slug 和标题规范
• 照片署名
• 代码块格式
• Lifecycle 部分结构
• 致谢格式

references/shiny-formatting.md - Shiny 博客要求：

• 带 YAML 锚点的 Quarto 前置内容
• 社交媒体卡片配置
• 导语段落和提示框
• 用于不同变体的选项卡组
• 行高亮和注释
• 视频嵌入
• 灵活的致谢方式

资源

• scripts/get_contributors.R：使用 usethis::use_tidy_thanks() 获取格式化的贡献者列表
• references/content-guidelines.md：通用内容最佳实践（与平台无关）
• references/tidyverse-formatting.md：Tidyverse 专属格式要求
• references/shiny-formatting.md：Shiny 专属格式要求

平台特定快速参考

Tidyverse 帖子模板

---
output: hugodown::hugo_document
slug: package-x-y-z
title: package x.y.z
date: YYYY-MM-DD
author: Your Name
description: >
    Brief description
photo:
  url: https://unsplash.com/photos/id
  author: Photographer Name
categories: [package]
tags: [package]
---

# package x.y.z

We're pleased to announce the release of package x.y.z...

```r
install.packages("package")
```

...

## Acknowledgements

A big thank you to all the folks who helped make this release happen:

[Contributors from get_contributors.R]

Shiny 帖子模板

---
title: Package Name x.y.z
description: &desc |
  Brief description of the release.
author: "Your Name"
date: "YYYY-MM-DD"

image: feature.png

open-graph:
  image: feature.png
  description: *desc
twitter-card:
  image: feature.png
  description: *desc
---

# package x.y.z

We're excited to announce package x.y.z...

[Installation for Python or R]

...

提示

• 先讲重大变更：在介绍新功能之前，先提供迁移指南
• 突出亮点：从最令人兴奋的功能讲起
• 展示胜过描述：多使用代码示例
• 多加链接：帮助读者找到更多信息
• 保持对话风格：像向同事讲解一样写作
• 真诚自然：热情应发自内心，而非营销话术