Contributing（貢献ガイド）

embedded-rust.com への貢献に興味を持っていただきありがとうございます。 このページでは、crate データの追加と記事（Markdown）投稿を中心に、PR（Pull Request）までの流れを説明します。

---

1. 貢献の種類

1) Crates の追加・修正

• 新しい crate を一覧に追加する
• 既存 crate の説明やリンクを更新する
• 互換性、注意点、導入例などを追記する

2) 記事の追加・修正

• 入門ガイド、手順書
• デバッグ手法や運用ノウハウ
• 既存記事の改善（誤字、構成、追記）

3) 小さな改善

• リンク切れ修正
• 表現の改善（初心者向けに言い換え）
• コード例の最新化

---

2. 事前準備

必要なもの

• Git
• Node.js >= 24（サイトのビルド・プレビュー用）
• pnpm（パッケージマネージャ）
• 任意: Rust（コード例の検証に便利）

リポジトリを fork / clone

1. GitHub 上でリポジトリを fork
2. ローカルに clone

git clone https://github.com/<your-account>/embedded-rust-com.git
cd embedded-rust-com

依存関係のインストール

pnpm install

ローカルプレビュー

pnpm dev

---

3. crate 追加方法（JSON 形式）

このサイトでは、crate 情報を src/content/crates/ 以下に 1ファイル = 1 crate の JSON で管理します。

3.1 追加するファイル

src/content/crates/<crate-name>.json

3.2 最短手順

1. 既存の JSON（例: defmt.json）をコピー
2. 内容を新しい crate に合わせて編集
3. ビルドして検証

pnpm build

Zod スキーマによる検証がビルド時に実行されます。不正データはビルドエラーになります。

3.3 JSON スキーマの主要フィールド

フィールド	型	必須	説明
name	string	Yes	crate 名（crates.io と一致）
descriptionJa	string	Yes	日本語での説明
categories	string[]	Yes	カテゴリ ID（先頭要素が主要カテゴリ）
repository	string	Yes	リポジトリ URL
cratesIo	string	Yes	crates.io URL
maturity	enum	Yes	experimental / alpha / beta / stable / mature
maintenance	enum	Yes	actively-developed / passively-maintained / …
targets	string[]	Yes	対象ターゲット
noStd	boolean	Yes	no_std 対応

完全なフィールド定義は src/schemas/crate-schema.ts を参照してください。

---

4. 記事投稿方法（Markdown）

4.1 記事の置き場所

• Dev Tips: src/content/docs/dev-tips/<topic>.md
• 技術比較: src/content/docs/other-tech/<topic>.md
• リファレンス: src/content/docs/reference/<topic>.md

4.2 frontmatter

---
title: 記事タイトル
description: 記事の要約
categories: ['Dev Tips']
tags: ['embedded', 'rust']
relatedCrates: ['defmt', 'probe-rs']
difficulty: beginner
draft: false
---

• draft: false のまま PR を出してください
• difficulty は beginner / intermediate / advanced のいずれか

---

5. Markdown ルール

コードブロックには言語指定（必須）

#![no_std]
#![no_main]

rustup target add thumbv7em-none-eabihf

[dependencies]
cortex-m = "0.7"

コマンドはコピペできる形に

• 出力ログは必要最小限に
• OS 依存（Linux / macOS / Windows）は分けて書く

リンクの貼り方

• 公式ドキュメントや docs.rs を優先
• サイト内リンクは相対パスを推奨

---

6. GitHub PR フロー

ブランチを切る

git checkout -b add-defmt-tip

変更をコミット

git add src/content/crates/my-new-crate.json
git commit -m "feat: add my-new-crate to crate catalog"

PR を作る

PR 本文には次を含めてください。

• 何を追加/修正したか（要約）
• 動作確認したこと（ローカルプレビュー、ビルド成功など）
• 影響範囲（既存ページの編集有無）

---

7. レビューチェックリスト

• frontmatter がある（draft: false）
• コードブロックに言語指定がある
• 手順が再現可能（前提・環境・コマンドが揃っている）
• 初心者が詰まりそうな点に補足がある
• 外部リンクが妥当（一次情報、リンク切れなし）

---

8. 迷ったとき

• 「この内容はここに書いて良い？」→ Issue で相談が最短です
• 既存記事の書きぶりに合わせるのが一番安全です
• 小さな PR ほど歓迎です（レビューが軽く、早くマージできます）