# Contributing to Cocoon

> **Note**: このCONTRIBUTING.mdは、Claude Code を使用して生成されました。

Cocoonプロジェクトへの貢献にご興味をお持ちいただき、ありがとうございます。このガイドでは、プロジェクトに貢献するための手順とガイドラインをご説明します。

## 目次

- [貢献の種類](#貢献の種類)
- [プロジェクト構成](#プロジェクト構成)
- [開発環境のセットアップ](#開発環境のセットアップ)
- [コード貢献の流れ](#コード貢献の流れ)
- [コーディング規約](#コーディング規約)
- [テスト・検証方法](#テスト検証方法)
- [問題報告（Issue）ガイドライン](#問題報告issueガイドライン)
- [翻訳協力](#翻訳協力)
- [ライセンスについて](#ライセンスについて)

## 貢献の種類

以下のような形でプロジェクトに貢献していただけます：

### コード改善・バグ修正
- バグの修正
- パフォーマンスの改善
- セキュリティの向上
- コードの最適化

### 新機能の提案と実装
- 新しい機能の提案
- 機能の実装
- 既存機能の改善

### 翻訳協力
- 多言語化の支援
- 既存翻訳の改善
- 新しい言語の追加

### ドキュメント改善
- ドキュメントの更新
- 使用例の追加
- 説明の明確化

### 問題報告
- バグの報告
- 改善提案
- 使用感のフィードバック

## プロジェクト構成

Cocoonテーマのフォルダ構成を理解しておくことで、効率的な開発が可能になります。

### ルートディレクトリ

```
cocoon/
├── │ WordPressテーマのコアファイル
│   ├── functions.php      # メインの関数ファイル
│   ├── style.css          # コンパイル済みCSS
│   ├── index.php          # メインテンプレート
│   ├── header.php         # ヘッダーテンプレート
│   ├── footer.php         # フッターテンプレート
│   └── その他のテンプレートファイル
│
└── ビルド・開発環境
    ├── package.json        # Node.js依存関係
    ├── gulpfile.js         # ビルド設定
    └── README.md           # プロジェクト情報
```

### 主要ディレクトリの説明

#### コアファイル群

| ファイル/フォルダ | 役割 |
|----------------|------|
| `functions.php` | テーマのメイン機能を定義、lib/のファイルを読み込み |
| `style.css` | コンパイル済みのメインCSS（直接編集非推奨） |
| `amp.css` | AMP用のCSS（scss/amp.scssから生成） |
| `javascript.js` | メインのJavaScriptファイル |
| `*.php` | WordPressテンプレートファイル群 |

#### lib/
**機能別のPHPモジュール群** — テーマの核心機能

```
lib/
├── _imports.php           # モジュール読み込み管理
├── admin.php              # 管理画面機能
├── settings.php           # 設定パネル
├── seo.php                # SEO最適化
├── sns.php                # SNS連携機能
├── shortcodes.php         # ショートコード定義
├── widgets/               # カスタムウィジェット
├── page-settings/         # 設定ページのサブモジュール
└── その他各種機能モジュール
```

#### scss/
**SCSSソースファイル** — CSSの原始コード

```
scss/
├── style.scss             # メインスタイルシートのソース
├── amp.scss               # AMP用スタイル
├── admin.scss             # 管理画面用スタイル
├── _editor-style.scss     # エディタースタイル
└── その他のコンポーネントSCSS
```

#### skins/
**スキン群** — テーマのデザインバリエーション

```
skins/
├── simple-blue/          # シンプルブルースキン
├── nagi/                 # 凪スキン
├── natural-green/        # ナチュラルグリーン
└── その他100+のスキン
```

各スキンフォルダには以下が含まれます：
- `style.css`: コンパイル済みCSS
- `scss/style.scss`: SCSSソースファイル
- `screenshot.jpg`: スキンのプレビュー画像

#### blocks/
**Gutenbergブロック** — 独立したWebpackプロジェクト

```
blocks/
├── package.json           # ブロック用依存関係
├── webpack.config.js      # Webpack設定
├── src/                   # ブロックのソースコード
└── dist/                  # ビルド済みファイル
```

#### その他の重要なフォルダ

| フォルダ | 役割 |
|---------|------|
| `css/` | 管理画面、エディター用なCSSファイル群 |
| `js/` | JavaScriptライブラリ群（第三者製） |
| `images/` | テーマ内で使用する画像ファイル |
| `languages/` | 翻訳ファイル（.po, .mo, .json） |
| `templates/` | ページテンプレート |
| `webfonts/` | アイコンフォント |
| `configs/` | 設定ファイル |

### 開発時の注意事項

#### 直接編集するファイル
- `lib/` 内のPHPファイル
- `scss/` 内のSCSSファイル
- `javascript.js`
- WordPressテンプレートファイル（*.php）
- `blocks/src/` 内のGutenbergブロックソースコード
- 各スキンの `scss/style.scss`

#### 編集してはいけないファイル
- `style.css` — SCSSから自動生成
- `amp.css` — SCSSから自動生成
- `css/` 内のCSSファイル — SCSSから自動生成
- `skins/*/style.css` — 各スキンのSCSSから自動生成
- `blocks/dist/` — Webpackから自動生成されたビルド済みファイル

## 開発環境のセットアップ

### 必要な環境

- **PHP**: 7.4以上
- **WordPress**: 5.0以上（最新版推奨）
- **Node.js**: 14.0.0以上
- **npm**: 6.9.0以上、7未満

### セットアップ手順

1. **リポジトリをフォーク**

   GitHub上でCocoonリポジトリをフォークしてください。

2. **ローカルにクローン**

   ```bash
   git clone https://github.com/[あなたのユーザー名]/cocoon.git
   cd cocoon
   ```

3. **依存関係のインストール**

   ```bash
   # メインプロジェクトの依存関係をインストール
   npm install

   # Gutenbergブロック開発の依存関係もインストール
   cd blocks
   npm install
   cd ..
   ```

4. **WordPress環境へのテーマ配置**

   クローンしたフォルダを WordPress の `wp-content/themes/` ディレクトリに配置してください。

5. **子テーマの設置（推奨）**

   開発時は[Cocoon子テーマ](https://github.com/yhira/cocoon-child)の使用を推奨します。

6. **VSCode開発環境の最適化**

   プロジェクトにはVSCode用の設定ファイルが含まれています。以下の拡張機能のインストールが推奨されます：

   ```bash
   # 推奨拡張機能（VSCode Extension ID）
   code --install-extension esbenp.prettier-vscode
   code --install-extension dbaeumer.vscode-eslint
   code --install-extension stylelint.vscode-stylelint
   code --install-extension bmewburn.vscode-intelephense-client
   code --install-extension wordpresstoolbox.wordpress-toolbox
   ```

   設定完了後、以下の機能が自動で有効になります：
   - **保存時フォーマット**: ファイル保存時の自動整形
   - **リアルタイムlint**: 入力中のエラー・警告表示
   - **PHP IntelliSense**: WordPress関数の自動補完
   - **ファイル種別最適化**: PHP/JS/SCSS個別の最適設定

## コード貢献の流れ

### 1. Issue確認

貢献する前に、[Issues](https://github.com/xserver-inc/cocoon/issues)で該当する問題が既に報告されていないか確認してください。

### 2. フォークとブランチ作成

```bash
# 上流リポジトリを追加
git remote add upstream https://github.com/xserver-inc/cocoon.git

# 最新の変更を取得
git fetch upstream
git checkout master
git merge upstream/master

# 新しいブランチを作成
git checkout -b feature/your-feature-name
```

### 3. 開発

- コードを変更する前に、該当部分のテストを実行してください
- 変更後は必ず動作確認を行ってください

### 4. ビルド

```bash
# CSS/SCSSファイルの変更の場合
npm run build

# 開発中の自動ビルド
npm run watch

# Gutenbergブロックのビルド（blocks内で作業する場合）
cd blocks
npm run build    # 本番用ビルド
npm run start    # 開発サーバー起動
```

### 5. コード品質チェック（推奨）

**利用可能なコマンド**：

```bash
# メインプロジェクト（プロジェクトルートで実行、blocks除外）
npm run lint             # JavaScript + CSS + PHP lintを実行
npm run lint:js          # JavaScript ESLint
npm run lint:css         # CSS/SCSS Stylelint
npm run lint:php         # PHP品質チェック（PHPCS）
npm run lint:js:fix      # JavaScript自動修正
npm run lint:css:fix     # CSS/SCSS自動修正
npm run lint:php:fix     # PHP自動修正（PHPCBF）
npm run format           # Prettier自動フォーマット
npm run format:check     # フォーマットチェックのみ

# Gutenbergブロック開発時（blocks内で実行、独立管理）
cd blocks
npm run lint             # 全体のlintチェック（JS + CSS + PHP）
npm run lint:js          # ブロック用JavaScript lint（wp-scripts）
npm run lint:js:fix      # ブロック用JavaScript自動修正
npm run lint:css         # ブロック用CSS lint（wp-scripts）
npm run lint:css:fix     # ブロック用CSS自動修正
npm run lint:php         # ブロック用PHP lint（PHPCS WordPress標準）
npm run lint:php:fix     # ブロック用PHP自動修正（PHPCBF）
npm run format           # Prettier自動フォーマット（wp-scripts）
npm run format:check     # フォーマットチェックのみ
```

#### VSCodeでの自動品質チェック

VSCodeを使用している場合、以下が自動で実行されます：
- **Ctrl+S（保存時）**: 自動フォーマット + lint修正
- **入力中**: リアルタイムエラー表示
- **Ctrl+Shift+P → "Format Document"**: 手動フォーマット

### 6. コミット

コミットメッセージは以下の形式で記述してください：

```
種類: 簡潔な説明（50文字以内）

詳細な説明（必要な場合）
- 変更理由
- 影響範囲
- 追加情報
```

コミット種類の例：
- `feat`: 新機能
- `fix`: バグ修正
- `docs`: ドキュメント更新
- `style`: コードスタイル（機能に影響しない変更）
- `refactor`: リファクタリング
- `perf`: パフォーマンス改善
- `test`: テスト追加・修正

### 7. プルリクエスト作成

1. 変更をプッシュ：
   ```bash
   git push origin feature/your-feature-name
   ```

2. GitHub上でプルリクエストを作成

3. プルリクエストのテンプレートに従って詳細を記述

## コーディング規約

プロジェクトでは**自動フォーマット**により一貫したコードスタイルを維持しています。

### 自動フォーマット設定

以下のファイルで統一されたコーディングスタイルが自動適用されます：

- **`.prettierrc.js`**: JavaScript/CSS/SCSS/JSON/Markdown
- **`.eslintrc.js`**: JavaScript品質・セキュリティルール
- **`.stylelintrc.js`**: CSS/SCSS品質ルール
- **`.editorconfig`**: 全ファイル共通の基本設定

### PHP

- [WordPress Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)に準拠
- インデントは**2スペース**（プロジェクト統一）
- 関数名やクラス名はWordPressの命名規則に従う

```php
// 良い例
function cocoon_get_user_data( $user_id ) {
  // 処理内容
  return $data;
}

// 悪い例
function getUserData($userId) {
  // 処理内容
}
```

### CSS/SCSS

- **自動フォーマット**: Prettierにより保存時自動整形
- インデントは2スペース
- Stylelintによる品質チェック

```scss
// 良い例（Prettierで自動整形される）
.example-class {
  background-color: #ffffff;
  color: #333333;
  display: flex;
  padding: 10px;
}
```

### JavaScript

- **自動フォーマット**: Prettierにより保存時自動整形
- **品質チェック**: ESLintによるリアルタイム検証
- セキュリティルール適用（`eval()`等の禁止）
- WordPress/jQuery環境最適化

```javascript
// 良い例（ESLint + Prettierで自動整形）
function exampleFunction() {
  var element = document.getElementById('example');
  if (element) {
    element.style.display = 'block';
  }
}
```

### VSCodeでの自動適用

設定完了後、以下が自動実行されます：

1. **保存時（Ctrl+S）**
   - Prettier自動フォーマット
   - ESLint自動修正（可能な部分）
   - Stylelint自動修正（可能な部分）

2. **入力中**
   - リアルタイムエラー・警告表示
   - 自動補完・IntelliSense

3. **コマンドパレット**
   - `Format Document`: 手動フォーマット
   - `Fix all auto-fixable Problems`: lint自動修正

### ビルドプロセスの確認

```bash
# CSS/SCSSのビルド確認
npm run build

# エラーがないことを確認
npm run watch

# Gutenbergブロックのビルド確認
cd blocks
npm install  # 初回のみ必要
npm run build
npm run start  # 開発サーバーでの確認
```

## テスト・検証方法

### Dockerローカル実機テスト

管理画面やフロントエンドの表示・挙動は、原則として `docker/README.md` に記載された
Dockerローカル実機テスト環境で確認してください。既定環境はWordPress 6.8系、PHP 8.3系、
MySQL 8.0で、Cocoon親テーマと子テーマを有効にした状態です。

プロジェクトルートからPowerShell 7で次の順に実行します。

```powershell
# コンテナ状態の確認
pwsh -NoProfile -File docker/dev.ps1 status

# 未起動時の環境起動
pwsh -NoProfile -File docker/dev.ps1 up

# DB確認が必要な場合だけphpMyAdminを起動
pwsh -NoProfile -File docker/dev.ps1 pma

# Compose構文、PHPUnit、Cocoon構文の一括確認
pwsh -NoProfile -File docker/dev.ps1 check
```

一括確認が成功した後、http://localhost:8085 でフロントエンド、
http://localhost:8085/wp-admin/ で管理画面の対象表示と操作を確認してください。
接続先、ローカル専用認証情報、任意起動のphpMyAdmin、検証済みバージョン、反復テストの詳細は
`docker/README.md` の「ローカル実機テスト環境」を参照してください。

リモートテストサーバーは、ローカル環境で再現できない挙動の確認や、リモート確認を明示的に
求められた場合に使用します。データベースとアップロードを削除する `docker compose down -v` は、
環境を初期化する必要がある場合を除いて実行しないでください。

## 問題報告（Issue）ガイドライン

### バグ報告

バグを見つけた場合は、以下の情報を含めて報告してください：

**必須情報**
- WordPress バージョン
- PHPバージョン
- ブラウザとバージョン
- Cocoonバージョン
- 問題の詳細な説明

**再現手順**
1. 具体的な操作手順
2. 期待される結果
3. 実際の結果

**環境情報**
- 使用中のプラグイン
- カスタマイズ内容
- エラーメッセージ（あれば）

### 機能要望

新機能の提案時は以下を含めてください：

- 機能の概要
- 必要性の説明
- 想定される実装方法
- 類似機能との比較

## 翻訳協力

CocoonはCrowdinを使用して多言語化を行っています。

### 翻訳への参加方法

1. [Cocoon Crowdinプロジェクト](https://crowdin.com/project/wp-cocoon)にアクセス
2. 参加申請（Join）を送信
3. 承認後、翻訳作業を開始

### 翻訳のガイドライン

- **一貫性**: 用語は統一して使用
- **自然さ**: その言語として自然な表現を使用
- **文脈**: UIの文脈を理解して翻訳
- **WordPress規約**: WordPressの翻訳規約に準拠

### 現在サポートされている言語

- 英語
- 中国(簡体語)
- 中国(繁体語)
- フランス語
- ドイツ語
- 韓国語
- ポルトガル語
- スペイン語

## ライセンスについて

Cocoonは**100% GPL**として公開されています。

### 貢献時の注意点

- 貢献されたコードはGPLライセンスとなります
- 第三者のコードを含む場合は、GPL互換であることを確認してください
- 著作権を侵害する内容は含めないでください

### ライセンス詳細

- ライセンス: [GNU General Public License v2.0](http://www.gnu.org/licenses/gpl-2.0.html)
- 再配布時は同じGPLライセンスを適用してください
- 商用・非商用を問わず自由に使用可能です

## コミュニティ

### サポート

- **公式サイト**: https://wp-cocoon.com/
- **GitHub Issues**: https://github.com/xserver-inc/cocoon/issues
- **フォーラム**: WordPress.orgコミュニティフォーラム

### 行動規範

- **敬意**: すべてのコントリビューターを尊重する
- **建設的**: 建設的なフィードバックを心がける
- **協力的**: チームワークを大切にする
- **包括的**: すべての人を歓迎する

## 謝辞

Cocoonプロジェクトへの貢献を検討していただき、ありがとうございます。皆様の協力により、Cocoonはより良いWordPressテーマになります。

質問がある場合は、[Issues](https://github.com/xserver-inc/cocoon/issues)で質問するか、[公式サイト](https://wp-cocoon.com/)をご確認ください。

---

**開発者**: わいひら ([yhira](https://github.com/yhira))
**最終更新**: 2025年9月