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

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