Package Release Post

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

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

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.

General Workflow

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

Step 1: Gather Information

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)

Step 2: Structure the Post

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

Step 3: Apply Content Guidelines

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

Step 4: Transform NEWS Content

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

Step 5: Apply Platform-Specific Formatting

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

Step 6: Generate Acknowledgements

Run the contributor script:

Rscript scripts/get_contributors.R

"owner/repo"

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

Rscript scripts/get_contributors.R

"owner/repo"

"v1.0.0"

Copy the markdown output into the Acknowledgements section.

Step 7: Review and Polish

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)

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

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

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 Platform-Specific Quick Reference Tidyverse Post Template

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

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]

...

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