# Contributing to gitstack
gitstackへの貢献に感謝します。本ドキュメントでは、開発に参加する際のルールとガイドラインを定めます。
## Table of Contents
- [Development Setup](#development-setup)
- [Coding Standards](#coding-standards)
- [Git Workflow](#git-workflow)
- [Commit Convention](#commit-convention)
- [Pull Request Guidelines](#pull-request-guidelines)
- [Testing Requirements](#testing-requirements)
- [Documentation Updates](#documentation-updates)
---
## Development Setup
### Prerequisites
- Rust 1.75.0+
- cargo
- Git
### Build
```bash
git clone https://github.com/Hiro-Chiba/gitstack.git
cd gitstack
cargo build
cargo test
```
---
## Coding Standards
### Naming Conventions
| Variables | snake_case | `commit_hash`, `file_path` |
| Functions | snake_case | `load_events()`, `render_graph()` |
| Types/Structs | PascalCase | `App`, `GitEvent` |
| Enums | PascalCase | `SidebarPanel` |
| Enum Variants | PascalCase | `SidebarPanel::Commits` |
| Constants | SCREAMING_SNAKE_CASE | `FOOTER_HEIGHT` |
| Modules | snake_case | `tui`, `graph` |
| Traits | PascalCase | `Renderable` |
### Code Style
- **インデント**: スペース4つ
- **行の長さ**: 最大100文字（ドキュメントは80文字推奨）
- **import順序**:
1. 標準ライブラリ (`std::`)
2. 外部クレート
3. 内部モジュール (`crate::`, `super::`)
```rust
// Good
use std::collections::HashMap;
use git2::Repository;
use ratatui::Frame;
use crate::app::App;
use crate::event::GitEvent;
```
### Documentation
- 公開API（`pub`）には必ずドキュメントコメント（`///`）を付ける
- 複雑なロジックにはインラインコメント（`//`）を付ける
- TODOコメントは `// TODO(username): description` 形式
### Error Handling
- `unwrap()` / `expect()` は原則禁止（テストコード除く）
- エラーは `anyhow::Result` で返す
- 致命的エラーのみ `panic!`
---
## Git Workflow
### Branch Strategy
```
main
│
└── feature/xxx # 新機能開発
└── fix/xxx # バグ修正
└── refactor/xxx # リファクタリング
└── docs/xxx # ドキュメント更新
└── test/xxx # テスト追加
```
### Branch Naming
```
<type>/<short-description>
Examples:
feature/add-sidebar-panel
fix/graph-rendering
refactor/dashboard-layout
docs/update-readme
```
---
## Commit Convention
[Conventional Commits](https://www.conventionalcommits.org/) に準拠する。
### Format
```
<type>(<scope>): <subject>
<body>
<footer>
```
### Type
| `feat` | 新機能追加 |
| `fix` | バグ修正 |
| `docs` | ドキュメントのみの変更 |
| `style` | コードの意味に影響しない変更（空白、フォーマット等） |
| `refactor` | バグ修正でも機能追加でもないコード変更 |
| `perf` | パフォーマンス改善 |
| `test` | テストの追加・修正 |
| `chore` | ビルドプロセスや補助ツールの変更 |
### Scope (optional)
変更対象のモジュールを指定:
- `app`, `tui`, `git`, `graph`, `stats`, `topology`
### Subject
- 命令形で記述（"Add", "Fix", "Update"）
- 先頭は大文字
- 末尾にピリオドを付けない
- 50文字以内
### Examples
```bash
# Good
feat(tui): Add dashboard status panel
fix(graph): Handle merge commit rendering
refactor(app): Simplify layout to dashboard-only
docs: Update installation instructions
chore: Bump ratatui to 0.30
# Bad
added new feature # 命令形でない、typeがない
feat: Fixed bug # typeとsubjectが矛盾
FEAT(UI): ADD FEATURE. # 大文字すぎ、ピリオド
```
### Breaking Changes
破壊的変更がある場合は `!` を追加し、footerに `BREAKING CHANGE:` を記述:
```
feat(app)!: Remove layout mode selection
BREAKING CHANGE: Dashboard is now the only layout. LayoutMode enum removed.
```
---
## Pull Request Guidelines
### Before Creating PR
1. **テスト通過を確認**
```bash
cargo test
cargo clippy -- -D warnings
cargo fmt --check
```
2. **コミット履歴を整理**
- 意味のある単位でコミットをまとめる
- WIPコミットは squash する
3. **ブランチを最新に**
```bash
git fetch origin
git rebase origin/main
```
### PR Title
コミットメッセージと同じ形式を使用:
```
feat(tui): Add dashboard sidebar panel
```
### PR Description Template
```markdown
## Summary
変更内容の概要を1-3行で記述
## Changes
- 変更点1
- 変更点2
- 変更点3
## Test Plan
- [ ] テスト項目1
- [ ] テスト項目2
## Screenshots (if applicable)
UIの変更がある場合はスクリーンショットを添付
## Related Issues
Closes #123
```
### Review Process
1. 自動チェック（CI）がすべてパス
2. 1名以上のレビュー承認
3. コンフリクトがない状態
4. Squash merge で main にマージ
### Merge Strategy
- **Squash and merge**: 複数コミットを1つにまとめてマージ
- マージコミットメッセージはPRタイトルを使用
---
## Testing Requirements
PRを作成する前に、以下のチェックをすべて通過させてください：
```bash
# テスト実行
cargo test
# Lintチェック（警告はエラーとして扱う）
cargo clippy -- -D warnings
# フォーマットチェック
cargo fmt --check
```
これらはCIでも自動チェックされます。
---
## Documentation Updates
機能追加・変更時のドキュメント更新ルール：
1. **README.md** と **README.ja.md** は常に同期
- 英語版を先に更新し、日本語版も同じ内容に更新
- 機能の追加・削除・変更は両方に反映
2. **実装済み機能のみ記載**
- 未実装の機能を記載しない
- シンプルで正確な表現を心がける
3. **キーバインド変更時**
- README.md / README.ja.md のキーバインドテーブルを更新
- ヘルプオーバーレイ（`?`キー）の内容を更新
4. **HISTORY.md更新**
- 新機能追加時はリリース時に `HISTORY.md` に追記（`make history` で自動生成可能）
---
## Questions?
不明点があれば、Issue を作成してください。