---
alwaysApply: false
description: Issue 管理・同期の運用ルール
---

# Issue管理ワークフロー (Issue Management Workflow)

## 日本語 (Japanese)

このリポジトリにおける Issue の管理および同期に関する運用ルールです。

### 1. 外部トラッカーとの同期

本プロジェクトでは、上流の Issue トラッカー (GitHub 互換 API) とローカルの Markdown ファイルを同期させて開発を進めます。

- **同期方向**: 原則として上流の Issue トラッカーが正（Source of Truth）です。
- **自動同期**: `node tools/scripts/sync_issues.mjs` を実行して、リモートの最新状態を `docs/issues/` に反映、またはローカルの新規 Issue をリモートに作成します。
- **Git追跡除外**: `docs/issues/` は `.gitignore` により Git 追跡から除外されています。
- **Issue 編集と 404**: 公式 GitBucket では、Issue 本体の PATCH（編集）API は全バージョンで未実装のため 404 になります。同期スクリプトは 404 時に **Create an issue comment** API で本文をコメントとして投稿するフォールバックを行うため、編集内容は Issue のコメントとしてリモートに残ります。

### 2. 記述規約

- **日英併記の義務化**:
  - すべての Issue は**日本語と英語を併記**しなければなりません。
  - 片方の言語だけで記述されている場合は、不足している言語の翻訳を補完してください。

### 3. クローズとクリーンアップ

- **手動クローズ**:
  - トラッカー API の制約により、スクリプトからの自動クローズは行いません。
  - 作業完了後、ローカル Markdown の `state` を `closed` にして同期スクリプトを実行すると、手動クローズ用のURLが表示されます。
- **ローカルの自動削除**:
  - 上流トラッカー側で `closed` になった Issue は、同期スクリプト実行時にローカルの Markdown ファイルが自動的に削除されます。

---

## English

Operational rules for managing and synchronizing issues in this repository.

### 1. Synchronization with External Tracker

In this project, development proceeds by synchronizing the upstream issue tracker (GitHub-compatible API) with local Markdown files.

- **Direction**: As a rule, the upstream issue tracker is the Source of Truth.
- **Auto-sync**: Run `node tools/scripts/sync_issues.mjs` to reflect the latest remote state in `docs/issues/` or create new local issues on the remote.
- **Git Ignore**: `docs/issues/` is excluded from Git tracking via `.gitignore`.
- **Issue edit and 404**: Official GitBucket does not implement the PATCH (edit) API for issues in any version, so it returns 404. The sync script falls back to posting the body as a comment via **Create an issue comment** API, so the edited content remains on the remote as an issue comment.

### 2. Writing Conventions

- **Mandatory Bilingual Description**:
  - All issues **must be written in both Japanese and English**.
  - If an issue is written in only one language, please supplement it with a translation in the missing language.

### 3. Closing and Cleanup

- **Manual Closing**:
  - Due to tracker API constraints, automatic closing from scripts is not performed.
  - After completing work, set the `state` of the local Markdown to `closed` and run the sync script to display the URL for manual closing.
- **Local Auto-deletion**:
  - Issues that are `closed` on the upstream tracker side will have their local Markdown files automatically deleted when the sync script is run.