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. 最終調整では適切な書式ガイドを参照する

プラットフォームの選択

このスキルでは、書式要件の異なる2つのブログプラットフォームに対応しています。

• 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」
• リポジトリ：「owner/repo」形式の GitHub リポジトリ
• パッケージの言語：R または Python
• NEWS の内容：パッケージの NEWS.md、CHANGELOG、または NEWS を読む
• パッケージの説明：主な目的を1文で説明する
• 前回リリースのタグ：貢献者情報の取得用（任意）
• アイキャッチ画像：フロントマター用（任意ですが推奨）

ステップ2：記事を構成する

次の順序に従って記事のアウトラインを作成します。

1. フロントマター：プラットフォーム固有の YAML（書式ガイドを参照）

2. タイトルと導入：

   • タイトル：パッケージ名とバージョン
   • 導入：パッケージの説明を1文にまとめた告知
   • インストール：インストールコマンドを記載したコードブロック
   • 概要：リリースノート全文へのリンクを含む簡潔な要約

3. 本文（適切なセクションを選択）：

   • 移行ガイド（破壊的変更がある場合）— 該当する場合は必ず最初に配置
   • ライフサイクルの変更（非推奨化、段階的な非推奨化、廃止）
   • 機能セクション（主要機能ごとに1つ、内容が伝わる見出しを付ける）
   • 軽微な改善（箇条書き）

4. 謝辞（適切な場合）：

   • scripts/get_contributors.R を使用する
   • 形式：「このリリースの実現に協力してくださった皆さんに、心より感謝します。」
   • GitHub へのリンクをコンマ区切りで記載

ステップ3：コンテンツのガイドラインを適用する

references/content-guidelines.md のベストプラクティスに従います。

• 導入のスタイル：「[ワクワク感を表す形容詞]、…のリリースをお知らせします。」
• セクションの順序：移行 → ライフサイクル → 機能 → 改善 → 謝辞
• トーン：親しみやすく、プロフェッショナルで、熱意がありつつも誠実に
• 技術的な正確さ：関数名は正確にバッククォートで囲む
• メリットを重視する：「何を」だけでなく「なぜ」を説明する
• コード例：現実的で、適切なコメントと書式を備えた例を使う

Step 4: NEWS の内容を変換する

NEWS.md の箇条書きを、ブログに適した内容に変換します。

• 機能を詳しく調べる：NEWS の箇条書きをそのままコピーするのではなく、関数のドキュメントを読み、PR を確認し、背景を理解します
• 背景を補足する：何が変わったかだけでなく、変更が重要な理由も説明します
• 完全なコード例を追加する：関数のシグネチャだけでなく、ワークフロー全体を含む現実的な使い方を示します
• まず概念を説明する：なじみのない機能については、コードを示す前に、機能の概要と仕組みを説明します
• テーマごとにまとめる：関連する NEWS 項目を、まとまりのあるセクションにまとめます
• 会話調にする：簡潔な箇条書きを、文章に書き換えます
• ドキュメントへのリンクを追加する：関連するドキュメントやリソースへのリンクを追加します
• 破壊的変更を強調する：移行方法を明確にします
• 複数言語の同等性（Shiny のみ）：Shiny ブログで R と Python のパッケージを扱う場合は、すべての例でタブセットを使い、両方の言語を示します

Step 5: プラットフォーム固有の書式を適用する

Tidyverse の投稿では、references/tidyverse-formatting.md を読み、次の形式を適用します。

• slug、photo.url、photo.author を含む hugodown フロントマター
• 固定の slug 形式：packagename-x-y-z（ドットをハイフンに置き換えます）
• R のコードブロックには r 言語識別子を付けます
• 謝辞は必ず最後のセクションに含めます

Shiny の投稿では、references/shiny-formatting.md を読み、次の形式を適用します。

• ソーシャルメディア用の YAML アンカーを含む Quarto フロントマター
• タイトルの形式は柔軟に設定できます
• Python/R または Express/Core のバリエーションにはタブセットを使います
• プラットフォーム固有のコードブロック属性を使います
• 謝辞は任意で、投稿の種類によって異なります
• リード段落、コールアウト、埋め込みメディアを使用できます

Step 6: 謝辞を作成する

コントリビューター用スクリプトを実行します。

Rscript scripts/get_contributors.R "owner/repo"

前のバージョンの開始タグ（または前回のリリース記事で使用したタグ）を指定する場合は、次のように実行します。

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

Markdown の出力を「謝辞」セクションにコピーします。

Step 7: 確認して仕上げる

プラットフォーム共通のチェックリスト：

• フロントマターに必須項目がすべて含まれている
• 冒頭でパッケージの目的が明確に示されている
• インストール用のコードブロックがある（該当する場合は両方の言語）
• セクションが論理的に整理されている
• コード例に適切な構文ハイライトが設定されている
• 関数名は括弧を含めてバッククォートで囲まれている：`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 のフロントマター構造
• スラッグとタイトルの規則
• 写真のクレジット表記
• コードブロックの書式設定
• ライフサイクルセクションの構造
• 謝辞の形式

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]

...

ヒント

• 破壊的変更を最初に：機能の紹介より前に移行ガイドを配置します
• 成果を強調する：最も魅力的な機能から始めます
• 説明するより実例を示す：コード例を積極的に使います
• リンクを豊富にする：読者が詳しい情報を見つけられるようにします
• 会話調を保つ：同僚に説明するように書きます
• 誠実である：熱意はマーケティング的な表現ではなく、心からのものにします