release-post

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Package Release Post

包发布博文

Create professional R/Python package release blog posts following Tidyverse or Shiny blog conventions.

创建遵循Tidyverse或Shiny博客规范的专业R/Python包发布博文。

Quick Start

快速开始

Identify the blog platform: Tidyverse (tidyverse.org) or Shiny (shiny.posit.co)
Verify NEWS.md or changelog exists for the package
Gather package info: name, version, repository (e.g., "tidyverse/dplyr")
Follow the workflow below
Use
```
scripts/get_contributors.R
```
to generate acknowledgments
Reference the appropriate formatting guide for final polish

确定博客平台：Tidyverse（tidyverse.org）或Shiny（shiny.posit.co）
确认包存在NEWS.md或更新日志
收集包信息：名称、版本、代码仓库（例如"tidyverse/dplyr"）
遵循下方工作流程
使用
```
scripts/get_contributors.R
```
生成致谢内容
参考对应的格式指南进行最终润色

Platform Selection

平台选择

This skill supports two blog platforms with different formatting requirements:

Tidyverse blog (tidyverse.org)
- Uses hugodown
- R packages primarily
- More rigid structure and conventions
- See
```
references/tidyverse-formatting.md
```
Shiny blog (shiny.posit.co)
- Uses Quarto
- R and Python packages
- More flexible, feature-focused structure
- See
```
references/shiny-formatting.md
```

First, determine which platform the post is for, then follow the general workflow and apply platform-specific formatting.

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

Tidyverse博客（tidyverse.org）
- 使用hugodown
- 主要面向R包
- 结构和规范更严格
- 参考
```
references/tidyverse-formatting.md
```
Shiny博客（shiny.posit.co）
- 使用Quarto
- 支持R和Python包
- 结构更灵活，以功能为核心
- 参考
```
references/shiny-formatting.md
```

首先请确定博文对应的发布平台，然后遵循通用工作流并应用平台特定的格式要求。

General Workflow

通用工作流

These steps apply to both platforms. Content guidelines are based on Tidyverse best practices but adapt them as needed for Shiny posts.

以下步骤适用于两个平台。内容规范基于Tidyverse最佳实践，可根据Shiny博文需求灵活调整。

Step 1: Gather Information

步骤1：收集信息

Collect required information:

Platform: Tidyverse or Shiny blog?
Package name and version: e.g., "dplyr 1.2.0" or "shiny 1.9.0"
Repository: GitHub repo in "owner/repo" format
Package language: R or Python
NEWS content: Read the package's NEWS.md, CHANGELOG, or NEWS
Package description: One-sentence core purpose
Previous release tag: For contributor fetching (optional)
Featured image: For frontmatter (optional but recommended)

收集所需的基础信息：

发布平台：Tidyverse还是Shiny博客？
包名称与版本：例如"dplyr 1.2.0"或"shiny 1.9.0"
代码仓库：格式为"所有者/仓库名"的GitHub仓库地址
包开发语言：R或Python
NEWS内容：读取包的NEWS.md、CHANGELOG或NEWS文件
包描述：一句话说明包的核心用途
上一个版本标签：用于拉取贡献者信息（可选）
特色图片：用于前言元数据（可选但推荐提供）

Step 2: Structure the Post

步骤2：搭建博文结构

Create the post outline following this order:

Frontmatter: Platform-specific YAML (see formatting references)
Title and Opening:
- Title: Package name and version
- Opening: Announcement with one-sentence package description
- Installation: Code block with installation command
- Overview: Brief summary with link to full release notes
Main Content (choose appropriate sections):
- Migration guide (if breaking changes) - Always first when present
- Lifecycle changes (deprecations, soft-deprecations, defunct)
- Feature sections (one per major feature, descriptive headings)
- Minor improvements (bulleted list)
Acknowledgements (when appropriate):
- Use
```
scripts/get_contributors.R
```
- Format: "A big thank you to all the folks who helped make this release happen:"
- Comma-separated GitHub links

按照以下顺序创建博文大纲：

前言元数据：平台专属的YAML配置（参考格式指南）
标题与开篇：
- 标题：包名+版本号
- 开篇：发布公告+一句话包描述
- 安装说明：包含安装命令的代码块
- 概述：简要总结，附带完整发布说明的跳转链接
主体内容（选择适配的板块）：
- 迁移指南（存在破坏性变更时）：如有该内容必须放在最前面
- 生命周期变更（废弃、软废弃、停止维护等说明）
- 功能板块（每个核心功能单独成块，使用描述性标题）
- 次要优化：项目符号列表形式
致谢（适用场景下添加）：
- 使用
```
scripts/get_contributors.R
```
  生成
- 格式："非常感谢所有助力本次发布的贡献者："
- 逗号分隔的GitHub链接列表

Step 3: Apply Content Guidelines

步骤3：遵循内容规范

Follow the best practices in

references/content-guidelines.md

Opening style: "We're [random adjective expressing excitement] to announce the release of..."
Section organization: Migration → Lifecycle → Features → Improvements → Acknowledgements
Tone: Conversational, professional, enthusiastic but authentic
Technical precision: Use exact function names in backticks
Focus on benefits: Explain "why" not just "what"
Code examples: Realistic, well-commented, properly formatted

遵循

references/content-guidelines.md

中的最佳实践：

开篇风格："我们非常[表达兴奋的随机形容词]地宣布...版本正式发布"
板块组织顺序：迁移指南 → 生命周期变更 → 新功能 → 优化 → 致谢
语气：口语化、专业、热情且真实
技术准确性：使用反引号包裹准确的函数名
聚焦价值：解释变更的价值，而不仅仅是变更内容
代码示例：贴近真实使用场景、注释完善、格式正确

Step 4: Transform NEWS Content

步骤4：转换NEWS内容

Convert NEWS.md bullets to blog-friendly content:

Research features thoroughly: Don't just copy NEWS bullets—read function docs, check PRs, understand the context
Expand context: Why changes matter, not just what changed
Add complete code examples: Show realistic usage with full workflows, not just function signatures
Explain concepts first: For unfamiliar features, explain what they are and how they work before showing code
Group thematically: Combine related NEWS items into coherent sections
Use conversational tone: Transform terse bullets into prose
Link documentation: Add relevant links to docs and resources
Highlight breaking changes: Make migration paths clear
Multi-language parity (Shiny only): For R+Python packages on the Shiny blog, ensure all examples show both languages in tabsets

将NEWS.md的列表内容转换为适合博客阅读的内容：

充分调研功能：不要直接复制NEWS的列表项，要阅读函数文档、查看PR、理解变更背景
补充上下文：说明变更的重要性，而不仅仅是变更了什么
添加完整代码示例：展示包含完整工作流的真实使用场景，而不仅仅是函数签名
先解释概念：对于用户不熟悉的功能，先说明功能是什么、如何工作，再展示代码
按主题分组：将相关的NEWS条目整合为连贯的板块
使用口语化语气：将简洁的列表项转换为通顺的正文
添加文档链接：关联相关的文档和资源链接
突出破坏性变更：明确说明迁移路径
多语言一致性（仅Shiny博客适用）：如果是Shiny博客上同时支持R和Python的包，确保所有示例通过标签页展示两种语言的实现

Step 5: Apply Platform-Specific Formatting

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

For Tidyverse posts, read

references/tidyverse-formatting.md

and apply:

hugodown frontmatter with
```
slug
```
,
```
photo.url
```
,
```
photo.author
```
Specific slug format:
```
packagename-x-y-z
```
(hyphens replace dots)
R code blocks with
```
r
```
language identifier
Acknowledgements always included as final section

For Shiny posts, read

references/shiny-formatting.md

and apply:

Quarto frontmatter with YAML anchors for social media
Flexible title formatting
Use tabsets for Python/R or Express/Core variations
Platform-specific code block attributes
Acknowledgements optional, varies by post type
May use lead paragraphs, callouts, embedded media

Tidyverse博文请阅读

references/tidyverse-formatting.md

并应用以下规则：

hugodown前言元数据需包含
```
slug
```
、
```
photo.url
```
、
```
photo.author
```
固定slug格式：
```
包名-x-y-z
```
（用连字符替换点号）
R代码块需添加
```
r
```
语言标识
致谢必须作为最后一个板块

Shiny博文请阅读

references/shiny-formatting.md

并应用以下规则：

Quarto前言元数据需包含社交媒体用的YAML锚点
灵活的标题格式
使用标签页展示Python/R或Express/Core版本差异
平台专属的代码块属性
致谢为可选，根据博文类型调整
可使用引导段落、提示框、嵌入媒体等元素

Step 6: Generate Acknowledgements

步骤6：生成致谢内容

Run the contributor script:

bash

Rscript scripts/get_contributors.R "owner/repo"

Or with a specific starting tag for the previous version (or tag used for last release post):

bash

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

Copy the markdown output into the Acknowledgements section.

运行贡献者拉取脚本：

bash

Rscript scripts/get_contributors.R "owner/repo"

如果需要指定上一个版本的起始标签（或上一次发布博文使用的标签）：

bash

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

将输出的markdown内容复制到致谢板块中。

Step 7: Review and Polish

步骤7：审核与润色

Platform-agnostic checklist:

Frontmatter complete with all required fields
Opening clearly states package purpose
Installation code block present (both languages if applicable)
Sections organized logically
Code examples use proper syntax highlighting
Function names in backticks with parentheses:
```
`function()`
```
Package names are not backticked or otherwise styled
Tone is conversational but not marketing-speak
No superlatives ("powerful", "rich", "seamless", etc.)
Features explained with context, not just listed
Concepts explained before showing code
All examples show R and Python variants (if applicable)
Links to full release notes included

Platform-specific checklist:

Tidyverse:

Slug format:
```
package-x-y-z
```
(hyphens, not dots)
Photo URL and author included
Acknowledgements section is final section
All contributors listed alphabetically

Shiny:

YAML anchors used for description (
```
&desc
```
,
```
*desc
```
)
Social media cards configured (
```
open-graph
```
,
```
twitter-card
```
)
Appropriate filters specified if using tabsets/shinylive
Tabsets used for showing paired variants (Python/R, Express/Core)
Multi-language tabsets used consistently (for R+Python packages only)

通用检查清单：

前言元数据包含所有必填字段
开篇明确说明包的用途
包含安装代码块（适用场景下需同时提供两种语言的安装命令）
板块逻辑清晰有序
代码示例使用正确的语法高亮
函数名使用带括号的反引号包裹：
```
`function()`
```
包名不使用反引号或其他特殊样式
语气口语化但不偏向营销话术
不使用夸大形容词（例如"强大的"、"丰富的"、"无缝的"等）
功能说明附带上下文，而不仅仅是罗列
展示代码前先解释相关概念
适用场景下所有示例都提供R和Python两种实现
包含完整发布说明的跳转链接

平台专属检查清单：

Tidyverse：

Slug格式符合要求：
```
包名-x-y-z
```
（使用连字符，不使用点号）
包含图片URL和作者信息
致谢板块是最后一个板块
所有贡献者按字母顺序排列

Shiny：

描述使用YAML锚点（
```
&desc
```
、
```
*desc
```
）
配置了社交媒体卡片（
```
open-graph
```
、
```
twitter-card
```
）
使用标签页/shinylive时指定了正确的筛选条件
使用标签页展示成对的版本差异（Python/R、Express/Core）
多语言标签页使用一致（仅针对同时支持R+Python的包）

Reference Documentation

参考文档

Load these as needed for detailed guidance:

需要详细指导时可查阅以下文档：

Content Guidelines

内容规范

references/content-guidelines.md
- General best practices for all release posts:

Post structure and organization
Opening style and tone
Section hierarchy and organization
Code examples and formatting
Before/after patterns
Acknowledgments conventions

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

博文结构与组织方式
开篇风格与语气要求
板块层级与组织规则
代码示例与格式要求
优化前后对比模式
致谢规范

Platform-Specific Formatting

平台专属格式要求

references/tidyverse-formatting.md
- Tidyverse blog requirements:

hugodown frontmatter structure
Slug and title conventions
Photo attribution
Code block formatting
Lifecycle section structure
Acknowledgements format

references/shiny-formatting.md
- Shiny blog requirements:

Quarto frontmatter with YAML anchors
Social media card configuration
Lead paragraphs and callouts
Tabsets for variants
Line highlighting and annotations
Video embedding
Flexible acknowledgements

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

hugodown前言元数据结构
slug与标题规范
图片署名要求
代码块格式
生命周期板块结构
致谢格式

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

带YAML锚点的Quarto前言元数据
社交媒体卡片配置
引导段落与提示框使用规范
版本差异标签页使用规则
行高亮与注释规则
视频嵌入要求
灵活的致谢规则

Resources

资源

scripts/get_contributors.R
: Fetch formatted contributor list using

usethis::use_tidy_thanks()

references/content-guidelines.md
: General content best practices (platform-agnostic)
references/tidyverse-formatting.md
: Tidyverse-specific formatting requirements
references/shiny-formatting.md
: Shiny-specific formatting requirements

scripts/get_contributors.R
：使用

usethis::use_tidy_thanks()

拉取格式化的贡献者列表

references/content-guidelines.md
：通用内容最佳实践（跨平台适用）
references/tidyverse-formatting.md
：Tidyverse专属格式要求
references/shiny-formatting.md
：Shiny专属格式要求

Platform-Specific Quick Reference

平台专属快速参考

Tidyverse Post Template

Tidyverse博文模板

markdown

---
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]
---

markdown

---
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...

install.packages("package")

...

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

install.packages("package")

...

Acknowledgements

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

[Contributors from get_contributors.R]

undefined

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

[Contributors from get_contributors.R]

undefined

Shiny Post Template

Shiny博文模板

markdown

---
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
---

markdown

---
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]

...

undefined

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

[Installation for Python or R]

...

undefined

Tips

提示

Breaking changes first: Put migration guides before features
Highlight the wins: Lead with the most exciting features
Show don't tell: Use code examples liberally
Link generously: Help readers find more information
Keep it conversational: Write like you're explaining to a colleague
Be authentic: Enthusiasm should feel genuine, not marketing-speak

破坏性变更优先：将迁移指南放在功能介绍之前
突出亮点：开篇优先介绍最受关注的新功能
展示而非说教：大量使用代码示例
多添加链接：方便读者获取更多信息
保持口语化：像和同事讲解一样撰写内容
保持真实：热情要发自内心，不要使用营销话术