Back to Details

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

快速开始

  1. Identify the blog platform: Tidyverse (tidyverse.org) or Shiny (shiny.posit.co)
  2. Verify NEWS.md or changelog exists for the package
  3. Gather package info: name, version, repository (e.g., "tidyverse/dplyr")
  4. Follow the workflow below
  5. Use 
    scripts/get_contributors.R
    to generate acknowledgments
  6. Reference the appropriate formatting guide for final polish
  1. 确定博客平台：Tidyverse（tidyverse.org）或Shiny（shiny.posit.co）
  2. 确认包存在NEWS.md或更新日志
  3. 收集包信息：名称、版本、代码仓库（例如"tidyverse/dplyr"）
  4. 遵循下方工作流程
  5. 使用
    scripts/get_contributors.R
    生成致谢内容
  6. 参考对应的格式指南进行最终润色

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:
  1. Frontmatter: Platform-specific YAML (see formatting references)
  2. 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
  3. 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)
  4. 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
按照以下顺序创建博文大纲：
  1. 前言元数据：平台专属的YAML配置（参考格式指南）
  2. 标题与开篇：
    • 标题：包名+版本号
    • 开篇：发布公告+一句话包描述
    • 安装说明：包含安装命令的代码块
    • 概述：简要总结，附带完整发布说明的跳转链接
  3. 主体内容（选择适配的板块）：
    • 迁移指南（存在破坏性变更时）：如有该内容必须放在最前面
    • 生命周期变更（废弃、软废弃、停止维护等说明）
    • 功能板块（每个核心功能单独成块，使用描述性标题）
    • 次要优化：项目符号列表形式
  4. 致谢（适用场景下添加）：
    • 使用
      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

package x.y.z

We're pleased to announce the release of package x.y.z...
r
install.packages("package")
...
We're pleased to announce the release of package x.y.z...
r
install.packages("package")
...

Acknowledgements

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

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