Skip to content

CONTRIBUTING.en.md

Latest commit

 

History

History
650 lines (447 loc) · 17.5 KB

CONTRIBUTING.en.md

File metadata and controls

650 lines (447 loc) · 17.5 KB
Raw

English | 日本語

Contributing to EpisodicRAG Plugin

Thank you for your interest in contributing to the EpisodicRAG plugin!

For AI Agents: See .claude/CLAUDE.md.

Supported Version: EpisodicRAG Plugin (see version.py)

This document explains how to set up the development environment, test code changes, and create pull requests.

Table of Contents

  1. Development Environment Setup
  2. Installation Methods
  3. Manual Script Execution
  4. Creating Pull Requests
  5. Coding Standards
  6. Testing
  7. Development Tools - Footer Checker, Link Checker (v4.1.0+)
  8. Persistent Path (v5.2.0+)
  9. Documentation
  10. Support

Development Environment Setup

Prerequisites

  • Python 3.x
  • Bash (Git Bash / WSL)
  • Claude Code environment

Installation Methods

There are two ways to test a plugin under development.

Pattern A: Via Local Marketplace (Recommended)

Overview: Install local plugins using Claude Code's /plugin install command. This allows testing with the same flow as actual marketplace distribution.

1. Verify Directory Structure

📖 Detailed Structure: ARCHITECTURE.md

plugins-weave/
├── .claude-plugin/                     # Marketplace configuration
│   └── marketplace.json
├── …                                   # Other plugins & root docs omitted
└── EpisodicRAG/                        # Plugin main body
    ├── .claude-plugin/                 # Plugin config & templates
    ├── scripts/                        # Clean Architecture (4 layers)
    │   ├── README.md                   # Python implementation reference
    │   ├── domain/                     # Core business logic
    │   ├── infrastructure/             # External concerns (I/O)
    │   ├── application/                # Use cases
    │   ├── interfaces/                 # Entry points
    │   ├── tools/                      # Development tools (v4.1.0+)
    │   └── test/
    ├── docs/                           # Documentation
    ├── skills/                         # Skill definitions
    └── ...

marketplace.json is already in place (included in the repository).

2. Register Local Marketplace

Execute the following in Claude Code:

# With relative path
/plugin marketplace add ./plugins-weave

# Or with absolute path
/plugin marketplace add C:\path\to\plugins-weave

Success output:

✅ Marketplace 'plugins-weave' added successfully

3. Install the Plugin

/plugin install EpisodicRAG@plugins-weave

Success output:

✅ Plugin 'EpisodicRAG' installed successfully

4. Initial Setup

@digest-setup

Configure interactively.

5. Verify Operation

@digest-auto

Expected output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 EpisodicRAG System Status
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
...

6. Development Iteration (After Code Changes)

After modifying plugin code, retest with:

# 1. Uninstall
/plugin uninstall EpisodicRAG@plugins-weave

# 2. Reinstall
/plugin install EpisodicRAG@plugins-weave

# 3. Setup (if needed)
@digest-setup

# 4. Verify operation
@digest-auto

Benefits:

  • Same test environment as actual marketplace distribution flow
  • Easy install/uninstall with /plugin install command
  • Easy version management

Pattern B: Manual Setup (Traditional Method)

Overview: Traditional method of directly manipulating the plugin directory.

1. Execute Setup

Run the @digest-setup skill in Claude Code, or use the Python CLI manually:

cd plugins-weave/EpisodicRAG/scripts

# Check status
python -m interfaces.digest_setup check

# Execute setup (specify JSON config)
python -m interfaces.digest_setup init --config '{"base_dir": ".", "paths": {"loops_dir": "data/Loops", "digests_dir": "data/Digests", "essences_dir": "data/Essences"}}'

2. Verify Configuration

python -m interfaces.digest_setup check

Example output:

{
  "status": "configured",
  "config_exists": true,
  "directories_exist": true,
  "config_file": "~/.claude/plugins/.episodicrag/config.json",
  "message": "Setup already completed"
}

(If identity_file_path is configured, "Identity File:" line is also displayed)

Benefits:

  • Simple (no marketplace registration required)
  • Same as existing workflow

Drawbacks:

  • May behave differently from marketplace distribution
  • Manual install/uninstall

Recommendation: During development, use Pattern A (Local Marketplace) to develop while verifying marketplace distribution behavior.

Manual Script Execution

Plugin internal scripts can also be executed directly (for debugging).

config_cli.py - Configuration Management (v4.0.0+)

Manages all path information and ensures Plugin self-containment.

cd plugins-weave/EpisodicRAG/scripts

# Display path information
python -m interfaces.config_cli --show-paths

# Output configuration JSON
python -m interfaces.config_cli

Direct CLI Execution of Skills (v4.0.0+)

Skills can be executed directly as Python scripts (for debugging):

cd plugins-weave/EpisodicRAG/scripts

# Equivalent to @digest-setup
python -m interfaces.digest_setup

# Equivalent to @digest-config
python -m interfaces.digest_config

# Equivalent to @digest-auto
python -m interfaces.digest_auto

Note: Usage via skills (@digest-setup, etc.) is still available.

Clean Architecture (4-Layer Structure)

Since v2.0.0, scripts/ adopts Clean Architecture (4-layer structure).

📖 Detailed Specification: Layer structure, dependency rules, and recommended import paths at ARCHITECTURE.md

📖 Architecture Selection Rationale: DESIGN_DECISIONS.md

v4.0.0 Changes: Configuration management (config) is distributed across subdirectories of each layer:

  • domain/config/ - Configuration constants, validation helpers
  • infrastructure/config/ - Configuration file I/O, path resolution
  • application/config/ - DigestConfig (Facade), service classes

Guide for Adding New Features

Feature to Add Location
Constants, type definitions, exceptions domain/
Configuration-related constants/validation domain/config/
File I/O, logging infrastructure/
Configuration file loading, path resolution infrastructure/config/
Business logic application/
Configuration management service (Facade) application/config/
External entry points interfaces/

Creating Pull Requests

  1. Fork this repository
  2. Create a new branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Create a Pull Request

Commit Messages

Use clear and concise commit messages:

  • feat: New feature
  • fix: Bug fix
  • docs: Documentation update
  • refactor: Refactoring
  • test: Test addition/modification

Coding Standards

  • Python: PEP 8 compliant
  • Bash: Verified with ShellCheck
  • Markdown: Clear and concise writing

Testing

📖 Test Details: See scripts/README.md for test directory structure and execution methods.

Quick Start

cd plugins-weave/EpisodicRAG/scripts

# Run all tests
python -m pytest test/ -v

# Layer-specific tests
python -m pytest test/domain_tests/ -v
python -m pytest test/config_tests/ -v

Manual Testing

After making changes, always test the following:

  1. Basic commands (/digest, @digest-auto, /dream-defrag)
  2. Skills (@digest-setup, @digest-config)
  3. Agent (@DigestAnalyzer)
  4. Hierarchical Digest generation flow

Development Environment Notes

Environment Mixing During Installation Testing

When development environment and installed plugin exist on the same machine, note the following:

Problem: Running @digest-setup etc. may create configuration files in the development folder

Verification method:

cd plugins-weave/EpisodicRAG
git status
# Expected: "nothing to commit, working tree clean"

Best Practices:

  1. Always check git status after installation
  2. Don't commit configuration files to the development folder
  3. Edit configuration on the installed plugin side
    • Installation location: ~/.claude/plugins/EpisodicRAG/

For details, see TROUBLESHOOTING.md.

Persistent Path (v5.2.0+)

EpisodicRAG configuration files and data are stored in the persistent path. This prevents configuration loss during plugin updates.

Default Path

~/.claude/plugins/.episodicrag/
├── config.json          # Configuration file
├── Loops/               # Loop files (configurable in config.json)
├── Digests/             # Digest files (configurable in config.json)
└── Identities/          # Identity files (configurable in config.json)

Override via Environment Variable (For Testing)

To change the persistent path during testing:

export EPISODICRAG_CONFIG_DIR=/tmp/test-episodicrag
python -m pytest test/ -v

📖 Details: ARCHITECTURE.md

Development Tools (v4.1.0+)

The scripts/tools/ directory contains quality management tools for documentation.

Security Analysis (Bandit) (v5.0.0+)

Bandit is used to scan for security vulnerabilities.

cd plugins-weave/EpisodicRAG

# Run security check
make security

# Or run directly
python -m bandit -r scripts/ --exclude scripts/test --severity-level medium

Example output (when no issues):

Run started...
...
Run completed
Total time: 0.5s
No issues identified.

Footer Checker (check_footer.py)

Verifies that each document's footer matches the format defined in _footer.md.

cd plugins-weave/EpisodicRAG/scripts

# Run check
python -m tools.check_footer

# Auto-fix
python -m tools.check_footer --fix

# Show summary only
python -m tools.check_footer --quiet

Example output:

Checking files in: docs/

OK (3):
  docs/README.md
  docs/dev/ARCHITECTURE.md
  docs/dev/DESIGN_DECISIONS.md

MISSING (1):
  docs/user/NEW_FILE.md

MISMATCH (1):
  docs/user/OLD_FILE.md

Summary: 3 OK, 1 MISSING, 1 MISMATCH

Link Checker (link_checker.py)

Validates relative links, anchor links, and composite links within Markdown files.

cd plugins-weave/EpisodicRAG/scripts

# Run validation
python -m tools.link_checker ../docs

# Verbose output
python -m tools.link_checker ../docs --verbose

# JSON output (for CI/CD)
python -m tools.link_checker ../docs --json

Example output:

Checking: docs/dev/ARCHITECTURE.md

BROKEN LINKS:
  Line 42: [config.md](./config.md)
    File not found: docs/dev/config.md
    Suggestion: Did you mean docs/dev/api/config.md?

  Line 85: [#invalid-anchor](#invalid-anchor)
    Anchor not found in document

Summary: 2 broken links in 1 file

Features:

  • Relative link validation (./file.md, ../file.md)
  • Anchor link validation (#section)
  • Composite link validation (file.md#section)
  • Broken link fix suggestions
  • JSON output (for CI/CD integration)

JSON Validator (validate_json.py)

Schema validation tool for config.json and config.template.json.

cd plugins-weave/EpisodicRAG/scripts

# Basic validation
python -m tools.validate_json config.json

# Template conformance check
python -m tools.validate_json config.json --template config.template.json

# Path format validation
python -m tools.validate_json config.json --check-paths

Features:

  • JSON syntax validation
  • Structure conformance check against config.template.json
  • Path format validation (relative/absolute paths)

Pre-commit Verification

Before committing documentation changes, run the following:

cd plugins-weave/EpisodicRAG/scripts
python -m tools.check_footer --quiet
python -m tools.link_checker ../docs --quiet

Ensure both tools complete without errors.

Documentation

Update documentation as needed when making code changes:

  • README.md - For general users
  • CONTRIBUTING.md - This file
  • docs/ - Detailed documentation

Single Source of Truth (SSoT) Principle

SSoT (Single Source of Truth) is the principle of not writing the same information in multiple places, but defining a canonical definition location and referencing it. This reduces maintenance burden during changes and prevents inconsistencies.

Documentation SSoT

Information SSoT (Canonical Definition Location) Reference Method
Terminology/concept definitions GLOSSARY.md (Glossary) > 📖 Details: [Glossary](../../GLOSSARY.md#section-name)
Footer _footer.md Unified at the end of each document
Configuration specification api/config.md Reference via link

Version SSoT

Version information's single source of truth is the version field in .claude-plugin/plugin.json.

// .claude-plugin/plugin.json
{
  "name": "EpisodicRAG",
  "version": "x.y.z",  // ← This is SSoT - see plugin.json for actual value
  ...
}
File Field Sync Method
.claude-plugin/plugin.json version SSoT (origin)
pyproject.toml version Manual sync
../.claude-plugin/marketplace.json plugins[].version Manual sync
CHANGELOG.md ## [x.x.x] Manual sync
README.md / README.en.md Version badge Automatic (dynamic badge reads the SSoT at display time)
docs/README.md Version badge Automatic (dynamic badge reads the SSoT at display time)
scripts/domain/version.py __version__ Automatic (dynamic loading)

📊 These syncs are verified by tests in scripts/test/domain_tests/test_version.py.

Dynamic Loading Mechanism:

scripts/domain/version.py dynamically loads the version from plugin.json:

from domain import __version__
print(__version__)  # Displays version from plugin.json

Release Procedure

When updating version, update 4 files:

  1. .claude-plugin/plugin.json - Update version field (SSoT)
  2. pyproject.toml - Update version to same value
  3. ../.claude-plugin/marketplace.json - Update plugins[0].version to same value
  4. CHANGELOG.md - Add new section ## [x.x.x] - YYYY-MM-DD (mirror it in CHANGELOG.en.md)

The version badges in the READMEs and docs/README.md are dynamic badges (shields.io reads the SSoT at display time), so they need no update.

# Verification (tests verify sync across all files)
cd scripts
python -m pytest test/domain_tests/test_version.py -v

Document Header Version

Some documents (ARCHITECTURE.md, API_REFERENCE.md, TROUBLESHOOTING.md) have version headers:

> **Supported Version**: EpisodicRAG Plugin ([version.py](scripts/domain/version.py) reference) / File Format 1.0

Recommended: Use dynamic reference format ([version.py](...) reference) to avoid manual updates.

Documentation Sync Process

Bilingual Documentation Policy

The EpisodicRAG plugin uses Japanese as the primary language and provides English versions of major documents.

  1. Primary Language: Japanese (日本語)
  2. Secondary Language: English

Translation Policy: Only major documents (README, CHANGELOG, CONTRIBUTING, QUICKSTART, CHEATSHEET) are maintained in English. Other documents remain Japanese-only to reduce translation maintenance costs.

Currently Synced Files

Japanese English Status
README.md README.en.md ✅ Synced
CHANGELOG.md CHANGELOG.en.md ✅ Synced
CONTRIBUTING.md CONTRIBUTING.en.md ✅ Synced
docs/user/QUICKSTART.md docs/user/QUICKSTART.en.md ✅ Synced
docs/user/CHEATSHEET.md docs/user/CHEATSHEET.en.md ✅ Synced

Sync Workflow

When updating Japanese documentation, also sync the corresponding English documentation.

  1. Edit Japanese version first - Edit the Japanese version first
  2. Update English version - Update English version in the same PR
  3. Add sync header - Add header at the top of English file: 
    <!-- Last synced: YYYY-MM-DD -->

Adding New Translations

When adding new English translations:

  1. Copy structure from Japanese version
  2. Translate content maintaining formatting
  3. Add sync header with date
  4. Update this table

Support

If you have questions or issues, please report them via GitHub Issues.

Thank you for your contribution!

EpisodicRAG by Weave | GitHub