Contributing to ReftrixMCP

July 12, 2026 · View on GitHub

日本語版 | English

日本語版

ReftrixMCPへの貢献に興味を持っていただき、ありがとうございます。このドキュメントでは、プロジェクトへの貢献方法について説明します。

目次

行動規範

このプロジェクトでは、すべての貢献者が敬意を持って協力し合うことを期待しています。建設的で歓迎的な環境を維持するため、以下を遵守してください:

  • 他の貢献者を尊重する
  • 建設的なフィードバックを提供する
  • プロフェッショナルな態度を保つ
  • 多様な視点を尊重する

はじめに

貢献方法

以下の方法でプロジェクトに貢献できます:

  • バグ報告: バグを発見した場合は、Issueを作成してください
  • 機能提案: 新機能のアイデアがあれば、Issueで提案してください
  • コード貢献: バグ修正や新機能の実装を行うPull Requestを送信してください
  • ドキュメント改善: ドキュメントの誤字修正や改善提案を歓迎します

初めての貢献

初めての方は、以下のラベルが付いたIssueから始めることをお勧めします:

  • good first issue: 初心者向けの簡単なタスク
  • help wanted: コミュニティからの助けを求めているタスク
  • documentation: ドキュメント関連のタスク

CLA（貢献者ライセンス契約）

重要: このプロジェクトへの貢献は、AGPL-3.0-onlyライセンスの下で提供されます。 Pull Requestの送信前に、CLAへの同意が必要です。

なぜCLAが必要か

ReftrixMCPはデュアルライセンスモデルであるAGPL-3.0-only + 商用ライセンスを採用しています。外部からの貢献を商用版にも含められるようにするため、初回のPull Request前にCLAへの同意が必要です。商用ライセンスについては licence@reftrix.io までお問い合わせください。

署名方法

  1. CLA.md の内容を確認してください

  2. Pull Requestの説明欄に以下のテキストを含めてください:

    I have read the CLA Document and I hereby agree to its terms.

  3. コミットメッセージに Signed-off-by を含めてください:

    git commit -s -m "feat: your feature description"

注意事項

  • CLAに同意いただけない場合、Pull Requestはマージできません
  • CLAは貢献者の著作権を保護しつつ、プロジェクトに再ライセンス権を付与するものです
  • 詳細は CLA.md をご確認ください

開発環境のセットアップ

前提条件

以下のツールがインストールされている必要があります:

  • Node.js: v20.19.0以上
  • pnpm: package.json の packageManager フィールドで指定されたバージョンを使用してください（Corepackで自動管理されます）
  • Docker: v24.0以上（データベース用）
  • Git: v2.40以上

セットアップ手順

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

    GitHubでリポジトリをフォークし、ローカルにクローンします:

    git clone https://github.com/YOUR_USERNAME/ReftrixMCP.git
cd ReftrixMCP

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

    pnpm install

  3. 環境変数の設定

    .env.exampleをコピーして.env.localを作成し、必要な環境変数を設定します:

    cp .env.example .env.local
# Prisma CLIは .env.local を読めないため、packages/database/.env が必要です
cp .env.local packages/database/.env

  4. データベースの起動

    Dockerを使用してPostgreSQLとpgvectorを起動します:

    pnpm docker:up

  5. データベースマイグレーション

    pnpm db:migrate
pnpm db:seed

  6. 開発ビルドの起動

    pnpm dev

ポート設定

ReftrixMCPは他のプロジェクトとの干渉を避けるため、21000オフセットを使用しています:

サービスポート
PostgreSQL26432
Prisma Studio26555
Redis27379

開発ワークフロー

ブランチ戦略

  • main: 本番環境用の安定版ブランチ
  • feature/*: 新機能開発用ブランチ
  • fix/*: バグ修正用ブランチ
  • chore/*: 設定・依存関係更新用ブランチ
  • hotfix/*: 緊急本番修正用ブランチ
  • docs/*: ドキュメント更新用ブランチ
  • test/*: テスト追加・修正用ブランチ
  • refactor/*: リファクタリング用ブランチ

開発の流れ

  1. Issueの作成（バグ報告や機能提案）

  2. ブランチの作成

    git checkout -b feature/your-feature-name

  3. テスト駆動開発（TDD）

    • まず失敗するテストを書く（Red）
    • テストをパスする最小限のコードを書く（Green）
    • コードをリファクタリングする（Refactor）

  4. コミット

    Conventional Commits形式でコミットメッセージを書く

  5. プルリクエストの作成

    mainブランチに対してPRを作成

  6. レビュー対応

    レビュアーからのフィードバックに対応

  7. マージ

    承認後、mainブランチにマージ

コーディング規約

TypeScript

  • strict mode: strict: trueを維持
  • any型禁止: unknownと型ガードを使用
  • 型注釈: 関数の戻り値の型を明示
  • 命名規則:
    • ファイル名: kebab-case（例: search-service.ts）
    • コンポーネント: PascalCase（例: SearchForm）
    • 関数: camelCase（例: handleSearch）
    • 定数: SCREAMING_SNAKE_CASE（例: MAX_RESULTS）
    • 型: PascalCase（例: SearchResult）

コンソールログ

  • 開発環境: 詳細なログを出力（[Module] Action: details形式）
  • 本番環境: エラーログのみ
if (process.env.NODE_ENV === "development") {
  console.log("[Search] Query:", { q, filters });
}

テスト

テスト駆動開発（TDD）必須

このプロジェクトではTDDを必須としています。

テストの種類

  1. ユニットテスト: 個別の関数・モジュールのテスト
  2. 統合テスト: 複数のモジュールの連携テスト
  3. E2Eテスト: ユーザーフローの動作テスト（Playwright）

テストコマンド

# 全テスト実行
pnpm test

# ウォッチモード
pnpm test:watch

# カバレッジレポート
pnpm test:coverage

# ユニットテストのみ（現在はmcp-serverパッケージのみ対応）
pnpm test:unit

# 統合テストのみ（現在はmcp-serverパッケージのみ対応）
pnpm test:integration

# スモークテスト（現在はmcp-serverパッケージのみ対応）
pnpm test:smoke

# E2Eテスト（Playwright、mcp-serverパッケージのみ）
pnpm --filter @reftrixmcp/mcp-server test:e2e:playwright

Note: test:unit, test:integration, test:smoke は現在 @reftrixmcp/mcp-server パッケージのみが対応しています。他パッケージでは pnpm test を使用してください。

テストカバレッジ目標

  • ステートメントカバレッジ: 80%以上
  • ブランチカバレッジ: 70%以上
  • 関数カバレッジ: 85%以上

E2Eテスト

  • Playwright + Chromiumを使用
  • スクリーンショット検証を実施
  • 主要なユーザーフローは100%カバー

コミットメッセージ規約

Conventional Commits

以下の形式でコミットメッセージを書いてください:

<type>(<scope>): <subject>

<body>

<footer>

Type

Prefix用途
feat:新機能
fix:バグ修正
test:テスト追加・修正
docs:ドキュメント
refactor:リファクタリング
style:コードスタイル変更
chore:ビルド・設定変更
perf:パフォーマンス改善
hotfix:緊急修正（本番障害対応）

例

feat(search): セマンティック検索機能を実装

- pgvectorを使用したベクトル検索
- HNSW m=16でP95 10.66ms達成
- 多言語対応Embedding (multilingual-e5-base)

Closes #123

ブランチ命名規則

必須フォーマット

<type>/<topic>

Type一覧

Type用途例
feature/新機能開発feature/semantic-search
fix/バグ修正fix/login-error
chore/設定・依存関係更新chore/update-deps
hotfix/緊急本番修正hotfix/critical-auth-bug
docs/ドキュメント更新docs/api-reference
test/テスト追加・修正test/search-unit-tests
refactor/リファクタリングrefactor/auth-module

命名ルール

  • 小文字のみ使用: feature/Search → ❌ / feature/search → ✅
  • ハイフン区切り: feature/semantic_search → ❌ / feature/semantic-search → ✅
  • 短く具体的に: feature/add-new-search-functionality-to-the-app → ❌ / feature/semantic-search → ✅

コミットルール

ブランチ内でのコミット

ブランチ作業中は自由にコミットできます:

  • ✅ WIP: 検索機能の実装中
  • ✅ fix typo
  • ✅ wip
  • ✅ 細かい単位での頻繁なコミット

mainブランチへのマージ時

Squash and Merge を使用し、以下のルールを適用:

Squashコミットメッセージテンプレート

<type>(<scope>): <簡潔な説明>

## 背景
<なぜこの変更が必要か>

## 変更内容
- <変更点1>
- <変更点2>
- <変更点3>

## 影響範囲
- 破壊的変更: あり/なし
- 設定変更: あり/なし
- DB Migration: あり/なし

Refs: #<issue番号>

Squashコミットメッセージ例

feat(search): セマンティック検索機能を実装

## 背景
キーワード検索では意図を正確に捉えられないため、
ベクトル検索による意味的な検索が必要。

## 変更内容
- pgvectorを使用したベクトル検索APIを追加
- HNSW m=16, ef_construction=64でインデックス作成
- multilingual-e5-baseによるEmbedding生成
- Hybrid Search（60% vector + 40% full-text）

## 影響範囲
- 破壊的変更: なし
- 設定変更: あり（EMBEDDING_MODEL環境変数追加）
- DB Migration: あり（embeddingsテーブル追加）

Refs: #123

プルリクエストルール

PRタイトル

PRタイトルは Squash時の最終コミットメッセージのsubject部分 として使用されます:

  • ✅ feat(search): セマンティック検索機能を実装
  • ✅ fix(auth): ログイン時のトークン検証エラーを修正
  • ❌ 検索機能の実装（type/scopeがない）
  • ❌ WIP: 検索機能（WIPはPRタイトルに使用不可）

PRサイズ制限

状態差分行数推奨アクション
✅ 適切400行以下そのままレビュー
⚠️ 要検討400-800行分割を検討
❌ 分割必須800行超必ず分割する

例外: 自動生成ファイル、ロックファイル、大規模リファクタリング（事前承認済み）

PR作成前チェックリスト

# 必須コマンド（すべてパスすること）
pnpm docs:generate && pnpm lint && pnpm typecheck && pnpm verify:listener-sync && pnpm test && pnpm docs:impact && pnpm docs:verify
  • すべてのテストがパス
  • ESLintエラー: 0件
  • TypeScriptエラー: 0件
  • pnpm verify:listener-sync がパス（Plan v4.2 SEC M-NEW-3 / INV-WORKER-NO-RESUME-001 enforce、worker.once('completed', ...) listener が同期実行のみであることを AST 解析で検証）
  • テストカバレッジ: 80%以上
  • 差分が800行以下（または分割済み）
  • CLA に同意済み（初回のみ）
  • コミットに Signed-off-by を含めている

Quality Gate コマンド列の記述規約

配下の Plan や 配下の ADR で Quality Gate コマンド列 (pnpm lint && pnpm typecheck && pnpm format:check && pnpm docs:verify && pnpm test 等) を記載する場合は、必ず fenced bash コードブロック (```bash で開始) で記述すること。docs-verify の qualityGateEnum() 抽出器は fenced bash ブロックのみを検出するため、インラインコードや plain text 列挙は Registry §15 EXEMPT scope safety net の整合性検証を bypass する。

Cross-ref: Registry §13.14 TPA-PHASE3-BATCH-C-01 (L) / Pre-PR Checklist /scripts/docs-verify-extract.mjs qualityGateEnum()` JSDoc。

マージルール

マージ方法

Squash and Merge のみ使用 - 他のマージ方法は禁止

方法許可理由
Squash and Merge✅履歴がクリーン
Merge Commit❌履歴が複雑になる
Rebase and Merge❌一貫性のため禁止

ブランチ保護ルール（main）

以下の条件を満たさないとマージ不可:

  • ✅ 1人以上のApprove
  • ✅ CIステータスチェック通過
  • ✅ 最新のmainとの同期（Require up-to-date）
  • ✅ 会話（コメント）の解決

Linear History

mainブランチは常に一直線の履歴を維持します:

main: A ─ B ─ C ─ D ─ E
         ↑       ↑
      Squash  Squash

リリースプロセス（npm 公開）

npm への公開は CI 駆動です（Trusted Publishing / OIDC、NPM_TOKEN 不使用）。以下の順序を守ってください:

  1. プライベートリポでバージョンを bump → bash scripts/sync-oss.sh で OSS リポ（TKMD/ReftrixMCP）へ git 同期する。sync-oss.sh は既定で npm publish を skip します（publish は CI 側の責務）。
  2. OSS リポで v* タグの GitHub Release を手動作成する: gh release create vX.Y.Z --repo TKMD/ReftrixMCP（prerelease は --prerelease を付与し、タグを vX.Y.Z-beta.N 形式にする）。
  3. release: published イベントが .github/workflows/publish.yml を起動する。verify job（Node 20、Environment gate なし）がタグ検証・build・全 tarball 検証を行う。
  4. publish job（Node 22）は npm-publish GitHub Environment の required-reviewer 承認 1 回の後にのみ実行され、5 パッケージ（@reftrixmcp/core → database → ml → webdesign-core → mcp-server）を Tier 順に npm Trusted Publishing (OIDC) + --provenance で公開する。再実行は冪等（公開済バージョンは skip）。
  5. Fallback（CI/OIDC 障害時のみ）: どうしても CI 経由で公開できない場合に限り、bash scripts/sync-oss.sh --local-publish でローカル npm publish を明示 opt-in できる（Environment 承認 gate を bypass するため通常経路では使わない）。旧 --skip-publish は現在 no-op（skip は既定）で、後方互換のために残されている。

maintainer の初回 cutover 前提（agent 実行不可、手動作業）: (a) npmjs.com で 5 パッケージそれぞれに Trusted Publisher 登録（publish workflow = .github/workflows/publish.yml、environment = npm-publish）、(b) GitHub の npm-publish Environment 作成 + required reviewers + v* deployment-branch/tag 制限の設定。recovery の workflow_dispatch は v* タグ ref から dispatch すること（Environment のタグ制限は github.ref を評価するため、branch から dispatch すると block される）。OIDC trust chain の end-to-end 検証は初回実 cutover でのみ可能。

CHANGELOG は 3 系統（root OSS-facing / 内部完全版 /apps/mcp-server/CHANGELOG.md パッケージレベル）を bilingual JP/EN で同期する（ §CHANGELOG管理ルール 参照）。

GitHub設定チェックリスト（管理者向け）

Settings → General → Pull Requests

  • Allow squash merging: ✅ ON
  • Allow merge commits: ❌ OFF
  • Allow rebase merging: ❌ OFF
  • Default commit message: Pull request title

Settings → Branches → Branch protection rules（main）

  • Require a pull request before merging: ✅ ON
  • Require approvals: 1
  • Require status checks to pass: ✅ ON
  • Require branches to be up to date: ✅ ON
  • Require conversation resolution: ✅ ON
  • Require linear history: ✅ ON

プルリクエストガイドライン

PRを作成する前に

  • すべてのテストがパスすることを確認
  • ESLintエラーが0件であることを確認
  • TypeScriptエラーが0件であることを確認
  • テストカバレッジが80%以上であることを確認
  • コミットをスカッシュしてクリーンな履歴にする

PRテンプレート

PRを作成すると、.github/pull_request_template.md のテンプレートが自動的に適用されます。テンプレートには以下のセクションが含まれます:

  • 背景 / 目的: なぜこの変更が必要か
  • 変更点（3〜7点）: 主な変更内容
  • 影響範囲 / 移行: 破壊的変更・設定変更・DB Migration の有無
  • テスト: Unit / Integration・E2E / 手動確認のチェックリスト
  • 関連Issue: Fixes / Refs
  • CLA: 初回コントリビューター向けCLA同意チェック
  • レビュアー向けチェックリスト: コードスタイル・テスト・ドキュメント確認
  • スクリーンショット: UI変更の場合のBefore/After

レビュープロセス

  1. 自動チェック: CI/CDで自動テストが実行されます
  2. コードレビュー: 少なくとも1人のレビュアーの承認が必要です
  3. 品質ゲート: 以下を満たす必要があります
    • テストカバレッジ 80%以上
    • ESLintエラー 0件
    • TypeScriptエラー 0件
    • セキュリティ脆弱性（High/Critical）0件

Issue報告

バグ報告

バグを報告する場合は、以下の情報を含めてください:

  • 再現手順: バグを再現する詳細な手順
  • 期待される動作: 本来どう動作すべきか
  • 実際の動作: 実際にどう動作したか
  • 環境情報: OS、ブラウザ、Node.jsバージョンなど
  • スクリーンショット: 該当する場合

バグ報告テンプレート

## バグの説明

バグの簡潔な説明

## 再現手順

1. '...'に移動
2. '...'をクリック
3. '...'までスクロール
4. エラーを確認

## 期待される動作

本来の動作の説明

## 実際の動作

実際の動作の説明

## 環境

- OS: [例: macOS 14.0]
- ブラウザ: [例: Chrome 120]
- Node.js: [例: v20.19.0]

## スクリーンショット

該当する場合はスクリーンショットを添付

機能提案

新機能を提案する場合は、以下の情報を含めてください:

  • 解決したい課題: なぜこの機能が必要か
  • 提案する解決策: どのような機能を追加するか
  • 代替案: 他に検討した解決策
  • 追加のコンテキスト: 参考資料や関連情報

質問・サポート

  • GitHub Discussions: 一般的な質問や議論
  • GitHub Issues: バグ報告や機能提案
  • Pull Requests: コード貢献

ご不明な点がありましたら、お気軽にIssueやDiscussionで質問してください。貢献をお待ちしております！

English Version

Thank you for your interest in contributing to ReftrixMCP! This document provides guidelines for contributing to the project.

Table of Contents

Code of Conduct

We expect all contributors to collaborate respectfully. To maintain a constructive and welcoming environment, please:

  • Respect other contributors
  • Provide constructive feedback
  • Maintain a professional attitude
  • Respect diverse perspectives

Getting Started (EN)

Ways to Contribute

You can contribute to the project in the following ways:

  • Bug Reports: Create an issue if you find a bug
  • Feature Requests: Suggest new features via issues
  • Code Contributions: Submit pull requests for bug fixes or new features
  • Documentation: Help improve documentation

First-Time Contributors

If you're new, we recommend starting with issues labeled:

  • good first issue: Simple tasks for beginners
  • help wanted: Tasks where we need community help
  • documentation: Documentation-related tasks

CLA (Contributor License Agreement)

Important: Contributions to this project are provided under the AGPL-3.0-only license. You must agree to the CLA before submitting a Pull Request.

Why is a CLA Required?

ReftrixMCP uses a dual-license model (AGPL-3.0-only + Commercial License). To allow external contributions to be included in the commercial version, all contributors must sign the CLA before their first Pull Request. For commercial licensing inquiries, contact licence@reftrix.io.

How to Sign

  1. Review the contents of CLA.md

  2. Include the following text in your Pull Request description:

    I have read the CLA Document and I hereby agree to its terms.

  3. Include Signed-off-by in your commit message:

    git commit -s -m "feat: your feature description"

Notes

  • Pull Requests cannot be merged without CLA agreement
  • The CLA protects contributor copyright while granting the project re-licensing rights
  • See CLA.md for full details

Development Setup (EN)

Prerequisites

Ensure you have the following tools installed:

  • Node.js: v20.19.0 or higher
  • pnpm: Use the version specified in the packageManager field of package.json (automatically managed by Corepack)
  • Docker: v24.0 or higher (for database)
  • Git: v2.40 or higher

Setup Steps

  1. Fork the Repository

    Fork the repository on GitHub and clone it locally:

    git clone https://github.com/YOUR_USERNAME/ReftrixMCP.git
cd ReftrixMCP

  2. Install Dependencies

    pnpm install

  3. Configure Environment Variables

    Copy .env.example to .env.local and configure required variables:

    cp .env.example .env.local
# Prisma CLI cannot read .env.local — packages/database/.env is required
cp .env.local packages/database/.env

  4. Start Database

    Use Docker to start PostgreSQL with pgvector:

    pnpm docker:up

  5. Run Database Migrations

    pnpm db:migrate
pnpm db:seed

  6. Start Development Build

    pnpm dev

Port Configuration

ReftrixMCP uses a 21000 offset to avoid conflicts:

ServicePort
PostgreSQL26432
Prisma Studio26555
Redis27379

Development Workflow (EN)

Branching Strategy

  • main: Stable production branch
  • feature/*: Feature development branches
  • fix/*: Bug fix branches
  • chore/*: Config/dependency update branches
  • hotfix/*: Critical production fix branches
  • docs/*: Documentation update branches
  • test/*: Test addition/modification branches
  • refactor/*: Refactoring branches

Development Flow

  1. Create an Issue (bug report or feature request)

  2. Create a Branch

    git checkout -b feature/your-feature-name

  3. Test-Driven Development (TDD)

    • Write failing tests (Red)
    • Write minimal code to pass (Green)
    • Refactor code (Refactor)

  4. Commit

    Use Conventional Commits format

  5. Create Pull Request

    Create a PR against the main branch

  6. Address Review Feedback

    Respond to reviewer comments

  7. Merge

    Merge to main after approval

Coding Standards (EN)

TypeScript

  • Strict mode: Maintain strict: true
  • No any: Use unknown with type guards
  • Type annotations: Explicitly type function return values
  • Naming conventions:
    • Files: kebab-case (e.g., search-service.ts)
    • Components: PascalCase (e.g., SearchForm)
    • Functions: camelCase (e.g., handleSearch)
    • Constants: SCREAMING_SNAKE_CASE (e.g., MAX_RESULTS)
    • Types: PascalCase (e.g., SearchResult)

Console Logging

  • Development: Output detailed logs ([Module] Action: details format)
  • Production: Error logs only
if (process.env.NODE_ENV === "development") {
  console.log("[Search] Query:", { q, filters });
}

Testing (EN)

Test Types

  1. Unit Tests: Test individual functions/modules
  2. Integration Tests: Test module interactions
  3. E2E Tests: Test user flows (Playwright)

Test Commands

# Run all tests
pnpm test

# Watch mode
pnpm test:watch

# Coverage report
pnpm test:coverage

# Unit tests only (currently mcp-server package only)
pnpm test:unit

# Integration tests only (currently mcp-server package only)
pnpm test:integration

# Smoke tests (currently mcp-server package only)
pnpm test:smoke

# E2E tests (Playwright, mcp-server package only)
pnpm --filter @reftrixmcp/mcp-server test:e2e:playwright

Note: test:unit, test:integration, test:smoke are currently only supported by the @reftrixmcp/mcp-server package. Use pnpm test for other packages.

Coverage Targets

  • Statement coverage: 80%+
  • Branch coverage: 70%+
  • Function coverage: 85%+

Commit Message Guidelines (EN)

Conventional Commits

Use the following format:

<type>(<scope>): <subject>

<body>

<footer>

Types

PrefixPurpose
feat:New feature
fix:Bug fix
test:Test addition/modification
docs:Documentation
refactor:Refactoring
style:Code style changes
chore:Build/config changes
perf:Performance improvements
hotfix:Emergency production fix

Example

feat(search): implement semantic search

- Vector search using pgvector
- HNSW m=16 achieving P95 10.66ms
- Multilingual embedding support

Closes #123

Branch Naming Conventions (EN)

Required Format

<type>/<topic>

Types

TypePurposeExample
feature/Feature developmentfeature/semantic-search
fix/Bug fixfix/login-error
chore/Config/dependency updateschore/update-deps
hotfix/Critical production fixhotfix/critical-auth-bug
docs/Documentation updatesdocs/api-reference
test/Test additions/modificationstest/search-unit-tests
refactor/Refactoringrefactor/auth-module

Naming Rules

  • Lowercase only: feature/Search -> invalid / feature/search -> valid
  • Hyphen-separated: feature/semantic_search -> invalid / feature/semantic-search -> valid
  • Short and specific: feature/add-new-search-functionality-to-the-app -> invalid / feature/semantic-search -> valid

Commit Rules (EN)

Commits Within Branches

You are free to commit at will within your branch:

  • WIP: implementing search feature
  • fix typo
  • wip
  • Frequent small commits are encouraged

Merging to main

Use Squash and Merge with the following rules:

Squash Commit Message Template

<type>(<scope>): <brief description>

## Background
<why this change is needed>

## Changes
- <change 1>
- <change 2>
- <change 3>

## Impact
- Breaking changes: yes/no
- Config changes: yes/no
- DB Migration: yes/no

Refs: #<issue number>

Pull Request Rules (EN)

PR Title

PR titles are used as the subject line of the final squash commit message:

  • feat(search): implement semantic search
  • fix(auth): fix token validation error on login
  • Search implementation (invalid - missing type/scope)
  • WIP: search feature (invalid - WIP not allowed in PR titles)

PR Size Limits

StatusDiff LinesRecommended Action
Appropriate400 lines or lessProceed with review
Needs consideration400-800 linesConsider splitting
Must splitOver 800 linesMust be split

Exceptions: Auto-generated files, lock files, large-scale refactoring (pre-approved)

Pre-PR Checklist

# Required commands (all must pass)
pnpm docs:generate && pnpm lint && pnpm typecheck && pnpm verify:listener-sync && pnpm test && pnpm docs:impact && pnpm docs:verify
  • All tests pass
  • ESLint errors: 0
  • TypeScript errors: 0
  • pnpm verify:listener-sync passes (Plan v4.2 SEC M-NEW-3 / INV-WORKER-NO-RESUME-001 enforce; AST gate verifying worker.once('completed', ...) listeners are synchronous-only)
  • Test coverage: 80%+
  • Diff under 800 lines (or already split)
  • CLA agreed (first time only)
  • Commits include Signed-off-by

Quality Gate Command Sequence Convention

When documenting Quality Gate command sequences (e.g. pnpm lint && pnpm typecheck && pnpm format:check && pnpm docs:verify && pnpm test) in Plans under or ADRs under sequences MUST be expressed as fenced bash code blocks (opening with ```bash). The docs-verify qualityGateEnum() extractor only detects fenced bash blocks; inline code or plain-text enumerations bypass the Registry §15 EXEMPT scope safety net consistency check.

Cross-ref: Registry §13.14 TPA-PHASE3-BATCH-C-01 (L) / Pre-PR Checklist /scripts/docs-verify-extract.mjs qualityGateEnum()` JSDoc.

Merge Rules (EN)

Merge Method

Squash and Merge only - other merge methods are prohibited

MethodAllowedReason
Squash and MergeYesClean history
Merge CommitNoHistory becomes complex
Rebase and MergeNoProhibited for consistency

Branch Protection Rules (main)

The following conditions must be met before merging:

  • 1 or more Approvals
  • CI status checks passed
  • Up to date with latest main (Require up-to-date)
  • All conversations resolved

Linear History

The main branch always maintains a linear history:

main: A - B - C - D - E
         ^       ^
      Squash  Squash

Release Process (npm Publish) (EN)

npm publishing is CI-driven (Trusted Publishing / OIDC, no NPM_TOKEN). Follow this order:

  1. Bump the version in the private repo, then run bash scripts/sync-oss.sh to git-sync to the OSS repo (TKMD/ReftrixMCP). sync-oss.sh skips npm publish by default (publishing is CI's responsibility).
  2. Manually create a GitHub Release for a v* tag in the OSS repo: gh release create vX.Y.Z --repo TKMD/ReftrixMCP (for a prerelease, add --prerelease and use a vX.Y.Z-beta.N tag).
  3. The release: published event triggers .github/workflows/publish.yml. The verify job (Node 20, no Environment gate) validates the tag, builds, and validates every tarball.
  4. The publish job (Node 22) runs only after one required-reviewer approval of the npm-publish GitHub Environment, publishing the 5 packages (@reftrixmcp/core → database → ml → webdesign-core → mcp-server) in Tier order via npm Trusted Publishing (OIDC) + --provenance. Re-runs are idempotent (already-published versions are skipped).
  5. Fallback (CI/OIDC failure only): only when publishing via CI is genuinely impossible, bash scripts/sync-oss.sh --local-publish explicitly opts into a local npm publish (do NOT use it in the normal flow — it bypasses the Environment-approval gate). The former --skip-publish is now a no-op (skip is the default), kept for backward compatibility.

Maintainer first-cutover prerequisites (manual, not agent-executable): (a) register a Trusted Publisher for each of the 5 packages on npmjs.com (publish workflow = .github/workflows/publish.yml, environment = npm-publish); (b) create the npm-publish GitHub Environment with required reviewers + a v* deployment-branch/tag restriction. A recovery workflow_dispatch MUST be dispatched from a v* tag ref (the Environment's tag restriction evaluates github.ref, so dispatching from a branch is blocked). The OIDC trust chain is verifiable end-to-end only at the first real cutover.

Keep the 3 CHANGELOGs (root OSS-facing / internal full /apps/mcp-server/CHANGELOG.mdpackage-level) in sync, bilingual JP/EN (see §CHANGELOG Management Rules).

GitHub Settings Checklist (For Administrators) (EN)

Settings -> General -> Pull Requests

  • Allow squash merging: ON
  • Allow merge commits: OFF
  • Allow rebase merging: OFF
  • Default commit message: Pull request title

Settings -> Branches -> Branch protection rules (main)

  • Require a pull request before merging: ON
  • Require approvals: 1
  • Require status checks to pass: ON
  • Require branches to be up to date: ON
  • Require conversation resolution: ON
  • Require linear history: ON

Pull Request Guidelines (EN)

Before Creating a PR

  • Ensure all tests pass
  • ESLint errors: 0
  • TypeScript errors: 0
  • Test coverage: 80%+
  • Squash commits for clean history
  • CLA agreed (first-time contributors only)
  • Commits include Signed-off-by

PR Template

When you create a PR, the template from .github/pull_request_template.md is automatically applied. The template includes the following sections:

  • Background / Purpose: Why this change is needed
  • Changes (3-7 items): Main changes as bullet points
  • Impact / Migration: Breaking changes, config changes, DB Migration status
  • Tests: Checklist for Unit / Integration & E2E / Manual verification
  • Related Issues: Fixes / Refs
  • CLA: CLA agreement checkbox for first-time contributors
  • Reviewer Checklist: Code style, tests, and documentation verification
  • Screenshots: Before/After for UI changes

Issue Reporting (EN)

Bug Reports

Include the following information:

  • Reproduction steps: Detailed steps to reproduce
  • Expected behavior: What should happen
  • Actual behavior: What actually happens
  • Environment: OS, browser, Node.js version
  • Screenshots: If applicable

Feature Requests

When proposing a new feature, please include:

  • Problem to solve: Why this feature is needed
  • Proposed solution: What feature to add
  • Alternatives considered: Other solutions you explored
  • Additional context: References or related information

Questions & Support

  • GitHub Discussions: General questions and discussions
  • GitHub Issues: Bug reports and feature requests
  • Pull Requests: Code contributions

Feel free to ask questions via issues or discussions. We look forward to your contributions!