chore: history cleanup
This commit is contained in:
64
guides/AUTONOMOUS_WORK_REMINDER.md
Normal file
64
guides/AUTONOMOUS_WORK_REMINDER.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Autonomous Work Reminder - TDD8 Implementation
|
||||
|
||||
## 🎯 MISSION: Complete Issue #50 - Metaschema Definition
|
||||
|
||||
**CRITICAL REMINDERS FOR AUTONOMOUS WORK:**
|
||||
|
||||
### 📋 TDD8 Workflow - NEVER SKIP STEPS
|
||||
1. **ISSUE** - Understand requirements (Issue #50 already analyzed)
|
||||
2. **TEST** - Write failing tests first (RED state required)
|
||||
3. **RED** - Verify tests fail before implementation
|
||||
4. **GREEN** - Implement minimal code to pass tests
|
||||
5. **REFACTOR** - Clean up code while keeping tests green
|
||||
6. **DOCUMENT** - Update documentation and help
|
||||
7. **REFINE** - Polish and optimize
|
||||
8. **PUBLISH** - Commit and close issue
|
||||
|
||||
### 🚨 AUTONOMOUS WORK PROTOCOLS
|
||||
|
||||
#### DO NOT FORGET TO:
|
||||
- ✅ Run tests after each change to verify state
|
||||
- ✅ Commit frequently with descriptive messages
|
||||
- ✅ Update CLI help when adding new features
|
||||
- ✅ Maintain backward compatibility
|
||||
- ✅ Follow existing code patterns and conventions
|
||||
- ✅ Use proper PYTHONPATH=. for all test runs
|
||||
- ✅ Close the issue when complete using: `make close-issue NUM=50`
|
||||
|
||||
#### QUALITY STANDARDS:
|
||||
- All tests must pass before moving to next TDD8 step
|
||||
- Code must follow existing project conventions
|
||||
- Documentation must be comprehensive
|
||||
- CLI integration must be complete and tested
|
||||
|
||||
#### ISSUE #50 SPECIFIC REQUIREMENTS:
|
||||
- Define JSON Schema metaschema for MarkiTect extensions
|
||||
- Support heading text capture
|
||||
- Support content field instructions
|
||||
- Support outline structure representation
|
||||
- Maintain backward compatibility with existing schemas
|
||||
- Include validation rules for new features
|
||||
|
||||
#### COMPLETION CRITERIA:
|
||||
- Metaschema JSON file created and validated
|
||||
- Tests cover all metaschema features
|
||||
- Documentation explains structure and usage
|
||||
- CLI can validate schemas against metaschema
|
||||
- All existing schemas still validate correctly
|
||||
|
||||
### 🔄 WORKFLOW COMMANDS
|
||||
```bash
|
||||
# Start work
|
||||
make tdd-start NUM=50
|
||||
|
||||
# Run tests
|
||||
PYTHONPATH=. python3 -m pytest tests/ --tb=short -q
|
||||
|
||||
# Commit work
|
||||
git add . && git commit -m "step: [TDD8_PHASE] description"
|
||||
|
||||
# Close issue when complete
|
||||
make close-issue NUM=50
|
||||
```
|
||||
|
||||
### 🎯 SUCCESS = Issue #50 completely implemented, tested, documented, and closed
|
||||
385
guides/ERROR_HANDLING_GUIDE.md
Normal file
385
guides/ERROR_HANDLING_GUIDE.md
Normal file
@@ -0,0 +1,385 @@
|
||||
# Error Handling Guidelines
|
||||
|
||||
**Version**: 1.0
|
||||
**Last Updated**: 2025-09-26
|
||||
**Purpose**: Maintain consistent, debuggable error handling across the codebase
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### ✅ DO
|
||||
```python
|
||||
# Specific exception handling with chaining
|
||||
try:
|
||||
result = api_call()
|
||||
except GiteaNotFoundError as e:
|
||||
raise IssueError(f"Issue #{number} not found") from e
|
||||
except GiteaAuthError as e:
|
||||
raise IssueError(f"Authentication failed") from e
|
||||
|
||||
# Logging for unexpected errors
|
||||
except Exception as e:
|
||||
logger.error(f"Unexpected error in {operation}", exc_info=True)
|
||||
raise DomainError(f"Operation failed: {operation}") from e
|
||||
```
|
||||
|
||||
### ❌ DON'T
|
||||
```python
|
||||
# Overly broad exception handling
|
||||
try:
|
||||
result = api_call()
|
||||
except Exception as e: # Too broad!
|
||||
raise IssueError(f"Failed: {e}")
|
||||
|
||||
# Silent error suppression
|
||||
try:
|
||||
process_file()
|
||||
except Exception:
|
||||
continue # Never do this!
|
||||
```
|
||||
|
||||
## 1. Exception Hierarchy
|
||||
|
||||
### Use Domain-Specific Exceptions
|
||||
|
||||
**Markitect Operations:**
|
||||
```python
|
||||
from markitect.exceptions import (
|
||||
MarkitectError, # Base for all Markitect operations
|
||||
DocumentError, # Document processing errors
|
||||
ASTError, # AST parsing/processing errors
|
||||
CacheError, # Cache operations errors
|
||||
DatabaseError, # Database operation errors
|
||||
SchemaError, # Schema validation/processing
|
||||
ValidationError, # Document validation errors
|
||||
GraphQLError, # GraphQL operations
|
||||
ConfigurationError # Configuration/setup errors
|
||||
)
|
||||
```
|
||||
|
||||
**TDDAI Operations:**
|
||||
```python
|
||||
from tddai.exceptions import (
|
||||
TddaiError, # Base for TDDAI operations
|
||||
WorkspaceError, # Workspace management
|
||||
IssueError, # Issue fetching/management
|
||||
TestGenerationError, # Test generation
|
||||
ConfigurationError # Configuration issues
|
||||
)
|
||||
```
|
||||
|
||||
**Gitea Operations:**
|
||||
```python
|
||||
from gitea.exceptions import (
|
||||
GiteaError, # Base Gitea error
|
||||
GiteaNotFoundError,# 404 responses
|
||||
GiteaAuthError, # Authentication failures
|
||||
GiteaApiError, # API errors with status codes
|
||||
GiteaConfigError # Configuration issues
|
||||
)
|
||||
```
|
||||
|
||||
## 2. Exception Translation Patterns
|
||||
|
||||
### Service Layer Pattern
|
||||
Services should translate external exceptions to domain exceptions:
|
||||
|
||||
```python
|
||||
class IssueService:
|
||||
def get_issue(self, issue_number: int) -> Issue:
|
||||
"""Get issue by number.
|
||||
|
||||
Raises:
|
||||
IssueError: When issue cannot be retrieved
|
||||
"""
|
||||
try:
|
||||
return self.gitea_client.issues.get(issue_number)
|
||||
except GiteaNotFoundError as e:
|
||||
raise IssueError(f"Issue #{issue_number} not found") from e
|
||||
except GiteaAuthError as e:
|
||||
raise IssueError(f"Authentication failed") from e
|
||||
except GiteaApiError as e:
|
||||
raise IssueError(f"API error: {e}") from e
|
||||
# Don't catch GiteaError - let specific exceptions handle it
|
||||
```
|
||||
|
||||
### File Operations Pattern
|
||||
```python
|
||||
def read_config_file(file_path: Path) -> dict:
|
||||
"""Read configuration file.
|
||||
|
||||
Raises:
|
||||
ConfigurationError: When file cannot be read or parsed
|
||||
"""
|
||||
try:
|
||||
content = file_path.read_text()
|
||||
return json.loads(content)
|
||||
except FileNotFoundError as e:
|
||||
raise ConfigurationError(f"Config file not found: {file_path}") from e
|
||||
except PermissionError as e:
|
||||
raise ConfigurationError(f"Permission denied reading: {file_path}") from e
|
||||
except json.JSONDecodeError as e:
|
||||
raise ConfigurationError(f"Invalid JSON in {file_path}: {e}") from e
|
||||
except Exception as e:
|
||||
logger.error(f"Unexpected error reading {file_path}", exc_info=True)
|
||||
raise ConfigurationError(f"Failed to read config: {file_path}") from e
|
||||
```
|
||||
|
||||
## 3. Exception Chaining Rules
|
||||
|
||||
### Always Chain Exceptions
|
||||
Use `raise ... from e` to preserve the original exception:
|
||||
|
||||
```python
|
||||
# ✅ CORRECT - preserves debugging information
|
||||
try:
|
||||
dangerous_operation()
|
||||
except SpecificError as e:
|
||||
raise DomainError("User-friendly message") from e
|
||||
|
||||
# ❌ WRONG - loses original exception context
|
||||
try:
|
||||
dangerous_operation()
|
||||
except SpecificError as e:
|
||||
raise DomainError(f"Failed: {e}")
|
||||
```
|
||||
|
||||
### Chain Standard Exceptions
|
||||
```python
|
||||
try:
|
||||
data = json.loads(content)
|
||||
except json.JSONDecodeError as e:
|
||||
raise ValidationError(f"Invalid JSON format") from e
|
||||
except (ValueError, TypeError) as e:
|
||||
raise ValidationError(f"Data validation failed") from e
|
||||
```
|
||||
|
||||
## 4. Logging Integration
|
||||
|
||||
### Log Before Re-raising
|
||||
```python
|
||||
import logging
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
try:
|
||||
complex_operation()
|
||||
except ExpectedError as e:
|
||||
# Don't log expected errors - let caller decide
|
||||
raise DomainError("Operation failed") from e
|
||||
except Exception as e:
|
||||
# Always log unexpected errors
|
||||
logger.error(
|
||||
"Unexpected error in complex_operation",
|
||||
extra={'context': {'param1': value1}},
|
||||
exc_info=True
|
||||
)
|
||||
raise DomainError("Unexpected failure") from e
|
||||
```
|
||||
|
||||
### Logging Levels
|
||||
- **ERROR**: Unexpected exceptions that indicate bugs
|
||||
- **WARNING**: Expected exceptions that are concerning (file not found, permission denied)
|
||||
- **INFO**: Normal error recovery (retries, fallbacks)
|
||||
- **DEBUG**: Detailed error context for development
|
||||
|
||||
## 5. Error Messages
|
||||
|
||||
### User-Facing Messages
|
||||
```python
|
||||
# ✅ GOOD - actionable and specific
|
||||
raise IssueError(f"Issue #{number} not found. Check the issue number and try again.")
|
||||
|
||||
# ✅ GOOD - includes context
|
||||
raise ConfigurationError(f"Missing required setting 'api_token' in {config_file}")
|
||||
|
||||
# ❌ BAD - too technical
|
||||
raise IssueError(f"HTTP 404 response from /api/v1/repos/owner/repo/issues/{number}")
|
||||
|
||||
# ❌ BAD - too vague
|
||||
raise IssueError("Something went wrong")
|
||||
```
|
||||
|
||||
### Include Context
|
||||
```python
|
||||
# Use MarkitectError's context parameter
|
||||
raise DocumentError(
|
||||
"Failed to parse document",
|
||||
cause=original_error,
|
||||
context={
|
||||
'file_path': str(file_path),
|
||||
'line_number': line_num,
|
||||
'operation': 'parse_markdown'
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
## 6. CLI Error Handling
|
||||
|
||||
### Consistent CLI Pattern
|
||||
```python
|
||||
def cli_command():
|
||||
"""CLI command that handles domain exceptions."""
|
||||
try:
|
||||
result = service.perform_operation()
|
||||
show_success(result)
|
||||
except DomainError as e:
|
||||
OutputFormatter.exit_with_error(str(e))
|
||||
# Don't catch Exception - let unexpected errors bubble up
|
||||
```
|
||||
|
||||
### Exit Codes
|
||||
- **0**: Success
|
||||
- **1**: Expected failure (user error, missing resource)
|
||||
- **2**: Configuration error
|
||||
- **>2**: Unexpected error (let Python handle it)
|
||||
|
||||
## 7. Anti-Patterns to Avoid
|
||||
|
||||
### 1. Overly Broad Exception Handling
|
||||
```python
|
||||
# ❌ NEVER DO THIS
|
||||
try:
|
||||
operation()
|
||||
except Exception as e:
|
||||
raise DomainError(f"Failed: {e}")
|
||||
```
|
||||
|
||||
### 2. Silent Error Suppression
|
||||
```python
|
||||
# ❌ NEVER DO THIS
|
||||
try:
|
||||
process_file(file)
|
||||
except Exception:
|
||||
continue # Silent failure!
|
||||
|
||||
# ✅ DO THIS INSTEAD
|
||||
try:
|
||||
process_file(file)
|
||||
except (OSError, IOError) as e:
|
||||
logger.warning(f"Could not process {file}: {e}")
|
||||
continue
|
||||
except Exception as e:
|
||||
logger.error(f"Unexpected error processing {file}: {e}", exc_info=True)
|
||||
continue
|
||||
```
|
||||
|
||||
### 3. Exception Conversion Without Context
|
||||
```python
|
||||
# ❌ WRONG - loses information
|
||||
try:
|
||||
api_call()
|
||||
except requests.RequestException as e:
|
||||
raise IssueError("API failed")
|
||||
|
||||
# ✅ CORRECT - preserves context
|
||||
try:
|
||||
api_call()
|
||||
except requests.ConnectionError as e:
|
||||
raise IssueError("Cannot connect to Gitea server") from e
|
||||
except requests.Timeout as e:
|
||||
raise IssueError("Gitea server request timed out") from e
|
||||
except requests.HTTPError as e:
|
||||
raise IssueError(f"HTTP error: {e.response.status_code}") from e
|
||||
```
|
||||
|
||||
## 8. Testing Error Handling
|
||||
|
||||
### Test Exception Translation
|
||||
```python
|
||||
def test_issue_not_found():
|
||||
"""Test that GiteaNotFoundError is translated to IssueError."""
|
||||
with mock.patch.object(gitea_client, 'get') as mock_get:
|
||||
mock_get.side_effect = GiteaNotFoundError("Not found")
|
||||
|
||||
with pytest.raises(IssueError) as exc_info:
|
||||
service.get_issue(123)
|
||||
|
||||
assert "Issue #123 not found" in str(exc_info.value)
|
||||
assert exc_info.value.__cause__.__class__ == GiteaNotFoundError
|
||||
```
|
||||
|
||||
### Test Error Messages
|
||||
```python
|
||||
def test_meaningful_error_messages():
|
||||
"""Test that error messages are user-friendly."""
|
||||
with pytest.raises(ConfigurationError) as exc_info:
|
||||
service.load_config("nonexistent.json")
|
||||
|
||||
error_msg = str(exc_info.value)
|
||||
assert "nonexistent.json" in error_msg
|
||||
assert "not found" in error_msg.lower()
|
||||
```
|
||||
|
||||
## 9. Refactoring Checklist
|
||||
|
||||
When refactoring error handling, use this checklist:
|
||||
|
||||
### 🔍 Identify Issues
|
||||
- [ ] Search for `except Exception:` patterns
|
||||
- [ ] Look for `continue` without logging in exception blocks
|
||||
- [ ] Find missing exception chaining (`raise ... from e`)
|
||||
- [ ] Check for generic error messages
|
||||
|
||||
### 🔧 Fix Patterns
|
||||
- [ ] Replace broad exceptions with specific ones
|
||||
- [ ] Add proper exception chaining
|
||||
- [ ] Implement logging for unexpected errors
|
||||
- [ ] Improve error message clarity
|
||||
- [ ] Add exception documentation to functions
|
||||
|
||||
### ✅ Verify
|
||||
- [ ] Test that CLI still works
|
||||
- [ ] Verify error messages are user-friendly
|
||||
- [ ] Check that debugging information is preserved
|
||||
- [ ] Ensure no silent failures remain
|
||||
|
||||
### 📚 Document
|
||||
- [ ] Update function docstrings with `Raises:` sections
|
||||
- [ ] Add new exceptions to relevant `__init__.py` files
|
||||
- [ ] Update this guide if new patterns emerge
|
||||
|
||||
## 10. Common Search Patterns
|
||||
|
||||
Use these patterns to find error handling issues:
|
||||
|
||||
```bash
|
||||
# Find overly broad exception handling
|
||||
rg "except Exception" --type py
|
||||
|
||||
# Find silent error suppression
|
||||
rg "except.*:\s*continue" --type py
|
||||
rg "except.*:\s*pass" --type py
|
||||
|
||||
# Find missing exception chaining
|
||||
rg "raise.*Error.*:" --type py | grep -v "from"
|
||||
|
||||
# Find exception handling without logging
|
||||
rg "except.*Exception.*:" -A 3 --type py | grep -v "log"
|
||||
```
|
||||
|
||||
## 11. Quick Migration Template
|
||||
|
||||
Use this template for migrating old exception handling:
|
||||
|
||||
```python
|
||||
# OLD PATTERN
|
||||
try:
|
||||
operation()
|
||||
except Exception as e:
|
||||
raise DomainError(f"Operation failed: {e}")
|
||||
|
||||
# NEW PATTERN
|
||||
try:
|
||||
operation()
|
||||
except SpecificError1 as e:
|
||||
raise DomainError(f"Specific failure case 1") from e
|
||||
except SpecificError2 as e:
|
||||
raise DomainError(f"Specific failure case 2") from e
|
||||
except Exception as e:
|
||||
logger.error("Unexpected error in operation", exc_info=True)
|
||||
raise DomainError(f"Unexpected operation failure") from e
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Good error handling makes debugging easier, provides better user experience, and prevents silent failures that hide bugs. When in doubt, be specific, preserve context, and log unexpected errors.
|
||||
311
guides/LEGACY_AGENT_GUIDE.md
Normal file
311
guides/LEGACY_AGENT_GUIDE.md
Normal file
@@ -0,0 +1,311 @@
|
||||
# Legacy Agent - Comprehensive Legacy Interface Management
|
||||
|
||||
## Overview
|
||||
|
||||
The Legacy Agent is a comprehensive system for managing legacy interface compatibility and lifecycle in the MarkiTect project. Built on top of the existing legacy compatibility system from Issue #39, it provides intelligent automation for deprecation management, migration assistance, and cleanup operations.
|
||||
|
||||
## Architecture
|
||||
|
||||
The legacy agent system consists of several interconnected components:
|
||||
|
||||
### Core Components
|
||||
|
||||
1. **LegacyRegistry** (`markitect/legacy/registry.py`)
|
||||
- Central registry for all legacy interfaces and versions
|
||||
- Tracks git commit bindings, deprecation status, and timelines
|
||||
- Maintains SQLite database for persistence
|
||||
- Records usage statistics for informed decision making
|
||||
|
||||
2. **LegacyAgent** (`markitect/legacy/agent.py`)
|
||||
- Intelligent automation engine for legacy lifecycle management
|
||||
- Handles deprecation progression, cleanup scheduling, and notifications
|
||||
- Configurable automation policies
|
||||
- Task queue system for scheduled operations
|
||||
|
||||
3. **LegacySwitch System** (`markitect/legacy/switches.py`)
|
||||
- CLI switch management (`--legacy-v1`, `--legacy-v2`, etc.)
|
||||
- Automatic switch generation based on registry
|
||||
- Deprecation warning integration
|
||||
- Legacy routing to appropriate implementations
|
||||
|
||||
4. **DeprecationManager** (`markitect/legacy/deprecation.py`)
|
||||
- Graduated deprecation warning system
|
||||
- Timeline-based status progression
|
||||
- User notification management
|
||||
|
||||
5. **GitStateTracker** (`markitect/legacy/git_tracker.py`)
|
||||
- Binds legacy versions to specific git commits
|
||||
- Enables precise version restoration
|
||||
- Validates compatibility snapshots
|
||||
|
||||
## CLI Interface
|
||||
|
||||
The legacy agent exposes comprehensive CLI commands under the `markitect legacy` namespace:
|
||||
|
||||
### Core Commands
|
||||
|
||||
#### `markitect legacy status`
|
||||
Shows status of all legacy interfaces with comprehensive metadata:
|
||||
```bash
|
||||
# Table view (default)
|
||||
markitect legacy status
|
||||
|
||||
# JSON output
|
||||
markitect legacy status --format json
|
||||
|
||||
# Include removed interfaces
|
||||
markitect legacy status --include-removed
|
||||
```
|
||||
|
||||
#### `markitect legacy analyze`
|
||||
Performs intelligent analysis of legacy interfaces:
|
||||
```bash
|
||||
# Analyze all interfaces
|
||||
markitect legacy analyze
|
||||
|
||||
# Analyze specific command
|
||||
markitect legacy analyze query
|
||||
|
||||
# Analyze specific version
|
||||
markitect legacy analyze query v1.0
|
||||
```
|
||||
|
||||
#### `markitect legacy migrate`
|
||||
Provides migration guidance with breaking change documentation:
|
||||
```bash
|
||||
# Get migration guide
|
||||
markitect legacy migrate query v1.0
|
||||
|
||||
# Migrate to specific version
|
||||
markitect legacy migrate query v1.0 --to-version v2.0
|
||||
```
|
||||
|
||||
#### `markitect legacy cleanup`
|
||||
Safely removes legacy interfaces with backup options:
|
||||
```bash
|
||||
# Interactive cleanup
|
||||
markitect legacy cleanup query v1.0
|
||||
|
||||
# Force cleanup without confirmation
|
||||
markitect legacy cleanup query v1.0 --force
|
||||
|
||||
# Cleanup without backup
|
||||
markitect legacy cleanup query v1.0 --no-backup
|
||||
```
|
||||
|
||||
### Agent Management
|
||||
|
||||
#### `markitect legacy agent-run`
|
||||
Executes automated maintenance cycles:
|
||||
```bash
|
||||
# Run maintenance
|
||||
markitect legacy agent-run
|
||||
|
||||
# Preview mode (dry run)
|
||||
markitect legacy agent-run --dry-run
|
||||
```
|
||||
|
||||
#### `markitect legacy agent-status`
|
||||
Shows agent configuration and task queue status:
|
||||
```bash
|
||||
# Table view
|
||||
markitect legacy agent-status
|
||||
|
||||
# JSON output
|
||||
markitect legacy agent-status --format json
|
||||
```
|
||||
|
||||
### Analytics & Reporting
|
||||
|
||||
#### `markitect legacy usage-stats`
|
||||
Displays usage patterns for informed decision making:
|
||||
```bash
|
||||
# All interfaces (30 days)
|
||||
markitect legacy usage-stats
|
||||
|
||||
# Specific command
|
||||
markitect legacy usage-stats --command query
|
||||
|
||||
# Extended period
|
||||
markitect legacy usage-stats --days 90
|
||||
```
|
||||
|
||||
#### `markitect legacy generate-guide`
|
||||
Creates detailed migration documentation:
|
||||
```bash
|
||||
# Output to stdout
|
||||
markitect legacy generate-guide query v1.0
|
||||
|
||||
# Save to file
|
||||
markitect legacy generate-guide query v1.0 --output migration_guide.md
|
||||
```
|
||||
|
||||
## Legacy Interface Lifecycle
|
||||
|
||||
The system manages interfaces through a comprehensive lifecycle:
|
||||
|
||||
### Status Progression
|
||||
|
||||
1. **CURRENT** - Active implementation
|
||||
2. **DEPRECATED** - Marked for eventual removal, warnings shown
|
||||
3. **LEGACY** - Requires explicit `--legacy-vX` flag
|
||||
4. **SUNSET** - Final warning phase, scheduled for removal
|
||||
5. **REMOVED** - No longer available
|
||||
|
||||
### Automated Progression
|
||||
|
||||
The agent can automatically progress interfaces based on:
|
||||
- Time-based rules (e.g., deprecated → legacy after 90 days)
|
||||
- Usage patterns (e.g., unused interfaces move to sunset)
|
||||
- Manual scheduling
|
||||
- Policy configuration
|
||||
|
||||
### Agent Configuration
|
||||
|
||||
The agent behavior is configurable via `AgentConfig`:
|
||||
|
||||
```python
|
||||
config = AgentConfig(
|
||||
auto_progression=True, # Auto-progress deprecations
|
||||
cleanup_unused_days=180, # Cleanup after 6 months unused
|
||||
migration_guide_auto_generation=True, # Auto-generate guides
|
||||
notification_threshold_days=30, # Notify 30 days before removal
|
||||
max_concurrent_migrations=3, # Limit concurrent operations
|
||||
backup_before_cleanup=True # Always backup before removal
|
||||
)
|
||||
```
|
||||
|
||||
## Integration with Existing Legacy System
|
||||
|
||||
The agent builds on the foundation from Issue #39:
|
||||
|
||||
### Existing Components (Issue #39)
|
||||
- `markitect/legacy_compat.py` - Basic legacy switches and warnings
|
||||
- `LegacyVersions` registry with git commit binding
|
||||
- `LegacyMode` state management
|
||||
- Environment-based test detection
|
||||
|
||||
### New Agent Components
|
||||
- Advanced registry with database persistence
|
||||
- Intelligent lifecycle automation
|
||||
- Comprehensive CLI interface
|
||||
- Usage analytics and reporting
|
||||
- Migration assistance tools
|
||||
|
||||
### Compatibility
|
||||
The new system is fully backward compatible with existing legacy switches:
|
||||
- `--legacy-v39-pre` continues to work as before
|
||||
- Existing deprecation warnings are preserved
|
||||
- Test environment detection still functions
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Setting Up Legacy Interface
|
||||
|
||||
```python
|
||||
from markitect.legacy import LegacyRegistry, LegacyStatus
|
||||
|
||||
registry = LegacyRegistry()
|
||||
|
||||
# Register a legacy version
|
||||
registry.register_legacy_interface(
|
||||
command='query',
|
||||
version='v1.0',
|
||||
git_commit='a1b2c3d4',
|
||||
status=LegacyStatus.DEPRECATED,
|
||||
deprecated_date='2025-09-30',
|
||||
removal_date='2025-12-30',
|
||||
breaking_changes=['Parameter renamed', 'Output format changed'],
|
||||
description='Legacy query with old parameter names'
|
||||
)
|
||||
```
|
||||
|
||||
### Adding Legacy Support to CLI Command
|
||||
|
||||
```python
|
||||
from markitect.legacy import legacy_option, with_legacy_support
|
||||
|
||||
@click.command()
|
||||
@click.argument('sql', type=str)
|
||||
@legacy_option('v1.0', 'Use v1.0 legacy behavior')
|
||||
@with_legacy_support('query')
|
||||
def query_command(sql, legacy_v1_0=False):
|
||||
# Modern implementation - legacy routing is automatic
|
||||
return execute_modern_query(sql)
|
||||
```
|
||||
|
||||
### Running Maintenance
|
||||
|
||||
```bash
|
||||
# Check what would be done
|
||||
markitect legacy agent-run --dry-run
|
||||
|
||||
# Execute maintenance
|
||||
markitect legacy agent-run
|
||||
|
||||
# Check results
|
||||
markitect legacy agent-status
|
||||
```
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Automated Management** - Reduces manual overhead of legacy maintenance
|
||||
2. **Data-Driven Decisions** - Usage analytics inform deprecation timelines
|
||||
3. **User Experience** - Clear migration paths and gradual warnings
|
||||
4. **Safety** - Backup and rollback capabilities
|
||||
5. **Comprehensive Tracking** - Complete audit trail of all operations
|
||||
6. **Policy Enforcement** - Consistent application of deprecation policies
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### Database Schema
|
||||
The registry uses SQLite with tables for:
|
||||
- `legacy_interfaces` - Interface definitions and metadata
|
||||
- `legacy_usage` - Usage tracking for analytics
|
||||
|
||||
### Task System
|
||||
The agent uses a persistent task queue for:
|
||||
- Scheduled deprecation progressions
|
||||
- Cleanup operations
|
||||
- Notification delivery
|
||||
- Migration guide generation
|
||||
|
||||
### Git Integration
|
||||
Version bindings enable:
|
||||
- Precise restoration of legacy behavior
|
||||
- Validation of compatibility snapshots
|
||||
- Audit trail of changes
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
1. **Integration with CI/CD** - Automated testing of legacy interfaces
|
||||
2. **User Notification System** - Email/webhook notifications
|
||||
3. **Migration Assistance** - Interactive migration wizards
|
||||
4. **Advanced Analytics** - Usage heat maps and trend analysis
|
||||
5. **Policy Templates** - Pre-configured deprecation policies
|
||||
6. **Cross-Project Support** - Legacy management across multiple projects
|
||||
|
||||
## Getting Started
|
||||
|
||||
1. **Check Current Status**:
|
||||
```bash
|
||||
markitect legacy status
|
||||
```
|
||||
|
||||
2. **Run Analysis**:
|
||||
```bash
|
||||
markitect legacy analyze
|
||||
```
|
||||
|
||||
3. **Configure Agent**:
|
||||
```bash
|
||||
markitect legacy agent-status
|
||||
```
|
||||
|
||||
4. **Run Maintenance**:
|
||||
```bash
|
||||
markitect legacy agent-run --dry-run
|
||||
markitect legacy agent-run
|
||||
```
|
||||
|
||||
The legacy agent provides a complete solution for managing the entire lifecycle of deprecated interfaces, ensuring smooth transitions while maintaining backward compatibility.
|
||||
659
guides/LEGACY_COMPATIBILITY_SYSTEM_GUIDE.md
Normal file
659
guides/LEGACY_COMPATIBILITY_SYSTEM_GUIDE.md
Normal file
@@ -0,0 +1,659 @@
|
||||
# Legacy Compatibility System for MarkiTect CLI
|
||||
|
||||
## Overview
|
||||
|
||||
The Legacy Compatibility System provides comprehensive management of deprecated CLI interfaces through versioned switches, automated lifecycle management, and seamless migration assistance. This system enables gradual deprecation of features while maintaining backward compatibility and providing clear migration paths.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
CLI[CLI Commands] --> LS[Legacy Switches]
|
||||
LS --> LR[Legacy Registry]
|
||||
LR --> LA[Legacy Agent]
|
||||
LA --> GT[Git State Tracker]
|
||||
LA --> DM[Deprecation Manager]
|
||||
LA --> CL[Compatibility Layer]
|
||||
|
||||
GT --> Git[Git Repository]
|
||||
DM --> Warnings[Deprecation Warnings]
|
||||
CL --> Adapters[Parameter Adapters]
|
||||
|
||||
LA --> Automation[Automated Management]
|
||||
Automation --> Progression[Lifecycle Progression]
|
||||
Automation --> Cleanup[Legacy Cleanup]
|
||||
Automation --> Migration[Migration Assistance]
|
||||
```
|
||||
|
||||
## Key Components
|
||||
|
||||
### 1. Legacy Registry
|
||||
**Central management of legacy interfaces and versions**
|
||||
|
||||
- **Purpose**: Maintains authoritative database of all legacy interfaces
|
||||
- **Features**:
|
||||
- Version tracking with git commit bindings
|
||||
- Status lifecycle management (current → deprecated → legacy → sunset → removed)
|
||||
- Usage analytics and migration guidance
|
||||
- Import/export capabilities for backup and sharing
|
||||
|
||||
**Core API**:
|
||||
```python
|
||||
from markitect.legacy import LegacyRegistry, LegacyStatus
|
||||
|
||||
registry = LegacyRegistry()
|
||||
|
||||
# Register a legacy interface
|
||||
interface = registry.register_legacy_interface(
|
||||
command='query',
|
||||
version='v1.0',
|
||||
git_commit='abc123',
|
||||
status=LegacyStatus.DEPRECATED,
|
||||
migration_guide='Use new --format parameter',
|
||||
breaking_changes=['Parameter renamed', 'Output format changed']
|
||||
)
|
||||
|
||||
# Execute legacy implementation
|
||||
result = registry.execute_legacy('query', 'v1.0', *args, **kwargs)
|
||||
```
|
||||
|
||||
### 2. Legacy Switch System
|
||||
**CLI switches for version-controlled legacy behavior**
|
||||
|
||||
- **Purpose**: Provides `--legacy-v1`, `--legacy-v2` style switches
|
||||
- **Features**:
|
||||
- Automatic switch generation from registry
|
||||
- Deprecation warnings on usage
|
||||
- Parameter adaptation for compatibility
|
||||
- Graceful fallback to modern implementations
|
||||
|
||||
**Usage Patterns**:
|
||||
```python
|
||||
from markitect.legacy import legacy_option, with_legacy_support
|
||||
|
||||
# Method 1: Decorators for new commands
|
||||
@legacy_option('v1.0', 'Use v1.0 legacy behavior')
|
||||
@click.command()
|
||||
def my_command(legacy_v1_0=False):
|
||||
if legacy_v1_0:
|
||||
# Handle legacy behavior
|
||||
pass
|
||||
|
||||
# Method 2: Automatic legacy support
|
||||
@with_legacy_support('query')
|
||||
@click.command()
|
||||
def query_command(*args, **kwargs):
|
||||
# Modern implementation - legacy routing handled automatically
|
||||
pass
|
||||
```
|
||||
|
||||
### 3. Git State Tracker
|
||||
**Binding legacy versions to specific git commits**
|
||||
|
||||
- **Purpose**: Enable precise version restoration and validation
|
||||
- **Features**:
|
||||
- Current git state capture
|
||||
- Version-to-commit binding
|
||||
- File validation for legacy versions
|
||||
- Snapshot creation for testing
|
||||
|
||||
**Example**:
|
||||
```python
|
||||
from markitect.legacy import GitStateTracker
|
||||
|
||||
tracker = GitStateTracker()
|
||||
|
||||
# Bind current state to legacy version
|
||||
binding = tracker.bind_version_to_commit(
|
||||
command='query',
|
||||
version='v1.0',
|
||||
description='Query v1.0 with old parameters',
|
||||
validation_files=['markitect/cli.py', 'markitect/database.py']
|
||||
)
|
||||
|
||||
# Get commit for legacy version
|
||||
commit_hash = tracker.get_commit_for_version('query', 'v1.0')
|
||||
```
|
||||
|
||||
### 4. Deprecation Manager
|
||||
**Graduated deprecation warnings and lifecycle management**
|
||||
|
||||
- **Purpose**: Structured deprecation process with appropriate warnings
|
||||
- **Features**:
|
||||
- Four-level warning system (INFO → WARNING → CRITICAL → ERROR)
|
||||
- Timeline-based progression
|
||||
- Migration report generation
|
||||
- Usage analytics and recommendations
|
||||
|
||||
**Deprecation Levels**:
|
||||
- **INFO**: Initial deprecation notice (90 days)
|
||||
- **WARNING**: Standard deprecation warning (60 days)
|
||||
- **CRITICAL**: Final warning before removal (30 days)
|
||||
- **ERROR**: Blocks execution (post-removal)
|
||||
|
||||
### 5. Compatibility Layer
|
||||
**Bridge between legacy and modern interfaces**
|
||||
|
||||
- **Purpose**: Translate legacy parameters to modern equivalents
|
||||
- **Features**:
|
||||
- Parameter name mapping
|
||||
- Value transformation
|
||||
- Return format adaptation
|
||||
- Fallback behavior for missing functionality
|
||||
|
||||
**Parameter Mapping Example**:
|
||||
```python
|
||||
from markitect.legacy.compatibility import InterfaceAdapter, ParameterMapping
|
||||
|
||||
adapter = InterfaceAdapter(
|
||||
legacy_version='v1.0',
|
||||
parameter_mappings=[
|
||||
ParameterMapping(
|
||||
legacy_name='sql_query', # Old parameter
|
||||
modern_name='sql', # New parameter
|
||||
required=True
|
||||
),
|
||||
ParameterMapping(
|
||||
legacy_name='output_format',
|
||||
modern_name='format',
|
||||
transformer=lambda x: {'pretty': 'table', 'raw': 'simple'}.get(x, x)
|
||||
)
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### 6. Legacy Agent
|
||||
**Automated legacy interface lifecycle management**
|
||||
|
||||
- **Purpose**: Intelligent automation of legacy management tasks
|
||||
- **Features**:
|
||||
- Automatic deprecation progression
|
||||
- Cleanup scheduling and execution
|
||||
- Migration assistance coordination
|
||||
- Usage monitoring and analytics
|
||||
|
||||
**Agent Operations**:
|
||||
```python
|
||||
from markitect.legacy import LegacyAgent
|
||||
|
||||
agent = LegacyAgent()
|
||||
|
||||
# Run maintenance cycle
|
||||
summary = agent.run_maintenance()
|
||||
|
||||
# Force cleanup of specific version
|
||||
success = agent.force_cleanup('old_command', 'v1.0')
|
||||
|
||||
# Schedule migration assistance
|
||||
agent.schedule_migration_assistance('query', 'v1.0', target_date='2024-12-31')
|
||||
```
|
||||
|
||||
## Implementation Guide
|
||||
|
||||
### Step 1: Setup Legacy Registry
|
||||
|
||||
```python
|
||||
# Initialize registry and register legacy interfaces
|
||||
from markitect.legacy import LegacyRegistry, LegacyStatus
|
||||
from datetime import datetime, timedelta
|
||||
|
||||
registry = LegacyRegistry()
|
||||
|
||||
# Register deprecated version
|
||||
registry.register_legacy_interface(
|
||||
command='query',
|
||||
version='v1.0',
|
||||
git_commit='a1b2c3d4', # Commit where v1.0 was current
|
||||
status=LegacyStatus.DEPRECATED,
|
||||
deprecated_date=(datetime.now() - timedelta(days=90)).isoformat(),
|
||||
removal_date=(datetime.now() + timedelta(days=60)).isoformat(),
|
||||
description='Legacy query with sql_query parameter',
|
||||
breaking_changes=[
|
||||
'Parameter sql_query renamed to sql',
|
||||
'Output format changed'
|
||||
],
|
||||
migration_guide='''
|
||||
Migration steps:
|
||||
1. Change --sql_query to positional sql argument
|
||||
2. Update --output_format values (pretty→table, raw→simple)
|
||||
3. Adapt result parsing for new format
|
||||
''',
|
||||
implementation=legacy_v1_implementation
|
||||
)
|
||||
```
|
||||
|
||||
### Step 2: Add Legacy Switches to CLI Commands
|
||||
|
||||
```python
|
||||
# Option 1: Manual legacy option addition
|
||||
@click.command()
|
||||
@click.argument('sql', type=str)
|
||||
@click.option('--format', '-f', default='simple')
|
||||
@legacy_option('v1.0', 'Use v1.0 legacy behavior (deprecated)')
|
||||
def query_command(sql, format, legacy_v1_0=False):
|
||||
if legacy_v1_0:
|
||||
# Use legacy registry
|
||||
registry = LegacyRegistry()
|
||||
return registry.execute_legacy('query', 'v1.0', sql=sql, format=format)
|
||||
else:
|
||||
# Modern implementation
|
||||
return execute_modern_query(sql, format)
|
||||
|
||||
# Option 2: Automatic legacy support
|
||||
@with_legacy_support('query')
|
||||
@click.command()
|
||||
def query_command(sql, format):
|
||||
# Modern implementation only - legacy handled automatically
|
||||
return execute_modern_query(sql, format)
|
||||
```
|
||||
|
||||
### Step 3: Setup Compatibility Adapters
|
||||
|
||||
```python
|
||||
from markitect.legacy.compatibility import CompatibilityLayer, InterfaceAdapter, ParameterMapping
|
||||
|
||||
compatibility = CompatibilityLayer()
|
||||
|
||||
# Create adapter for parameter changes
|
||||
adapter = InterfaceAdapter(
|
||||
legacy_version='v1.0',
|
||||
parameter_mappings=[
|
||||
ParameterMapping(
|
||||
legacy_name='sql_query',
|
||||
modern_name='sql'
|
||||
),
|
||||
ParameterMapping(
|
||||
legacy_name='output_format',
|
||||
modern_name='format',
|
||||
transformer=lambda x: {'pretty': 'table', 'raw': 'simple'}.get(x, x)
|
||||
)
|
||||
],
|
||||
return_transformer=lambda result: {
|
||||
'status': 'success',
|
||||
'data': result,
|
||||
'version': 'v1.0'
|
||||
}
|
||||
)
|
||||
|
||||
compatibility.register_adapter('query', adapter)
|
||||
```
|
||||
|
||||
### Step 4: Configure Automated Management
|
||||
|
||||
```python
|
||||
from markitect.legacy import LegacyAgent
|
||||
from markitect.legacy.agent import AgentConfig
|
||||
|
||||
# Configure agent
|
||||
config = AgentConfig(
|
||||
auto_progression=True,
|
||||
cleanup_unused_days=180,
|
||||
migration_guide_auto_generation=True,
|
||||
notification_threshold_days=30
|
||||
)
|
||||
|
||||
agent = LegacyAgent(config=config)
|
||||
|
||||
# Setup scheduled maintenance (via cron, systemd, etc.)
|
||||
# 0 2 * * * /usr/local/bin/markitect legacy agent-maintenance
|
||||
```
|
||||
|
||||
### Step 5: Add Legacy Management Commands
|
||||
|
||||
```python
|
||||
@click.group('legacy')
|
||||
def legacy_commands():
|
||||
"""Legacy interface management."""
|
||||
pass
|
||||
|
||||
@legacy_commands.command('status')
|
||||
def legacy_status():
|
||||
"""Show all legacy interfaces."""
|
||||
registry = LegacyRegistry()
|
||||
# Display legacy interface status
|
||||
|
||||
@legacy_commands.command('migrate')
|
||||
@click.argument('command')
|
||||
@click.argument('version')
|
||||
def legacy_migrate(command, version):
|
||||
"""Get migration guidance."""
|
||||
registry = LegacyRegistry()
|
||||
migration = registry.get_migration_path(command, version)
|
||||
# Display migration guide
|
||||
```
|
||||
|
||||
## Lifecycle Management
|
||||
|
||||
### Deprecation Progression
|
||||
|
||||
1. **Current** → **Deprecated** (Manual)
|
||||
- Developer marks feature as deprecated
|
||||
- INFO level warnings begin
|
||||
- Feature still works normally
|
||||
|
||||
2. **Deprecated** → **Legacy** (90 days)
|
||||
- WARNING level warnings
|
||||
- `--legacy-vX` flag required
|
||||
- Compatibility layer handles differences
|
||||
|
||||
3. **Legacy** → **Sunset** (60 days)
|
||||
- CRITICAL level warnings
|
||||
- Final warning phase
|
||||
- Migration assistance activated
|
||||
|
||||
4. **Sunset** → **Removed** (30 days)
|
||||
- Feature no longer available
|
||||
- ERROR level blocking
|
||||
- Cleanup and removal
|
||||
|
||||
### Automated Tasks
|
||||
|
||||
The Legacy Agent performs these automated tasks:
|
||||
|
||||
- **Daily**: Check for progression opportunities
|
||||
- **Weekly**: Generate usage reports and migration recommendations
|
||||
- **Monthly**: Clean up unused legacy interfaces
|
||||
- **On-demand**: Force cleanup, migration assistance, compatibility testing
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Basic Legacy Support
|
||||
|
||||
```bash
|
||||
# Modern usage
|
||||
markitect query "SELECT * FROM files" --format=table
|
||||
|
||||
# Legacy v1.0 usage (with warning)
|
||||
markitect query --legacy-v1.0 --sql_query "SELECT * FROM files" --output_format=pretty
|
||||
|
||||
# Legacy v2.0 usage
|
||||
markitect query --legacy-v2.0 --database_query "SELECT * FROM files"
|
||||
```
|
||||
|
||||
### Legacy Management
|
||||
|
||||
```bash
|
||||
# Show all legacy interfaces
|
||||
markitect legacy status
|
||||
|
||||
# Get migration guidance
|
||||
markitect legacy migrate query v1.0
|
||||
|
||||
# Force cleanup of legacy version
|
||||
markitect legacy cleanup query v1.0 --force
|
||||
|
||||
# Show agent status
|
||||
markitect legacy agent-status
|
||||
|
||||
# Run maintenance manually
|
||||
markitect legacy agent-maintenance
|
||||
```
|
||||
|
||||
### Compatibility Testing
|
||||
|
||||
```bash
|
||||
# Test parameter adaptation
|
||||
markitect legacy test-compatibility query v1.0 \
|
||||
--test-params '{"sql_query": "SELECT 1", "output_format": "pretty"}'
|
||||
|
||||
# Generate compatibility report
|
||||
markitect legacy compatibility-report query v1.0
|
||||
```
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
### Dual Interface Testing
|
||||
|
||||
The system supports testing both modern and legacy interfaces simultaneously:
|
||||
|
||||
```python
|
||||
def test_query_modern_and_legacy():
|
||||
"""Test both modern and legacy query interfaces."""
|
||||
|
||||
# Test modern interface
|
||||
result_modern = execute_modern_query("SELECT 1", "table")
|
||||
|
||||
# Test legacy interface
|
||||
registry = LegacyRegistry()
|
||||
result_legacy = registry.execute_legacy("query", "v1.0",
|
||||
sql_query="SELECT 1",
|
||||
output_format="pretty")
|
||||
|
||||
# Verify compatibility
|
||||
assert extract_data(result_modern) == extract_data(result_legacy)
|
||||
```
|
||||
|
||||
### Automated Test Generation
|
||||
|
||||
```python
|
||||
# Generate tests for legacy versions
|
||||
def generate_legacy_tests():
|
||||
registry = LegacyRegistry()
|
||||
for command in registry._interfaces:
|
||||
for version in registry.get_available_versions(command):
|
||||
create_compatibility_test(command, version)
|
||||
```
|
||||
|
||||
## Migration Assistance
|
||||
|
||||
### Automated Migration Reports
|
||||
|
||||
```python
|
||||
# Generate migration report
|
||||
report = deprecation_manager.generate_migration_report('query', 'v1.0')
|
||||
|
||||
# Report includes:
|
||||
# - Breaking changes
|
||||
# - Step-by-step migration guide
|
||||
# - Code examples
|
||||
# - Timeline and urgency
|
||||
# - Support resources
|
||||
```
|
||||
|
||||
### Interactive Migration Assistant
|
||||
|
||||
```bash
|
||||
# Interactive migration guidance
|
||||
markitect legacy migrate-assistant query v1.0
|
||||
|
||||
# Output:
|
||||
# 🔄 Migration Assistant for query v1.0
|
||||
#
|
||||
# Current usage detected:
|
||||
# ✓ Found 15 scripts using --sql_query parameter
|
||||
# ✓ Found 8 scripts using --output_format=pretty
|
||||
#
|
||||
# Migration steps:
|
||||
# 1. Update parameter names...
|
||||
# 2. Change format values...
|
||||
# 3. Test with new interface...
|
||||
#
|
||||
# Generate migration script? [y/N]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# Legacy system configuration
|
||||
export MARKITECT_LEGACY_AUTO_PROGRESSION=true
|
||||
export MARKITECT_LEGACY_CLEANUP_DAYS=180
|
||||
export MARKITECT_LEGACY_NOTIFICATION_DAYS=30
|
||||
export MARKITECT_LEGACY_QUIET_MODE=false
|
||||
|
||||
# Database locations
|
||||
export MARKITECT_LEGACY_DB_PATH="~/.markitect/legacy_registry.db"
|
||||
export MARKITECT_LEGACY_AGENT_DATA="~/.markitect/legacy_agent"
|
||||
```
|
||||
|
||||
### Configuration File
|
||||
|
||||
```yaml
|
||||
# .markitect/legacy_config.yml
|
||||
legacy:
|
||||
auto_progression: true
|
||||
cleanup_unused_days: 180
|
||||
migration_guide_auto_generation: true
|
||||
notification_threshold_days: 30
|
||||
max_concurrent_migrations: 3
|
||||
backup_before_cleanup: true
|
||||
|
||||
deprecation:
|
||||
info_duration_days: 90
|
||||
warning_duration_days: 60
|
||||
critical_duration_days: 30
|
||||
show_migration_guide: true
|
||||
block_on_error: true
|
||||
|
||||
compatibility:
|
||||
default_mode: adaptive
|
||||
strict_validation: false
|
||||
fallback_behavior: warn
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Registration Strategy
|
||||
|
||||
- **Register early**: Add legacy interfaces as soon as deprecation begins
|
||||
- **Comprehensive metadata**: Include detailed breaking changes and migration guides
|
||||
- **Git binding**: Always bind to specific commits for precise restoration
|
||||
- **Validation files**: Specify key files that define the legacy behavior
|
||||
|
||||
### 2. Deprecation Timeline
|
||||
|
||||
- **Generous timelines**: Allow sufficient time for migration (6+ months total)
|
||||
- **Clear communication**: Provide detailed warnings and migration guidance
|
||||
- **Usage monitoring**: Track legacy usage to inform timeline decisions
|
||||
- **Gradual progression**: Use the four-phase progression systematically
|
||||
|
||||
### 3. Compatibility Layer
|
||||
|
||||
- **Parameter mapping**: Handle all parameter name and format changes
|
||||
- **Return transformation**: Maintain expected output formats
|
||||
- **Error handling**: Provide graceful fallbacks for edge cases
|
||||
- **Performance**: Minimize overhead of compatibility translations
|
||||
|
||||
### 4. Testing Approach
|
||||
|
||||
- **Dual testing**: Test both legacy and modern interfaces
|
||||
- **Compatibility validation**: Ensure legacy interfaces produce equivalent results
|
||||
- **Migration testing**: Validate migration guides work correctly
|
||||
- **Agent testing**: Test automated lifecycle management
|
||||
|
||||
### 5. Migration Assistance
|
||||
|
||||
- **Proactive guidance**: Generate migration reports before removal
|
||||
- **Code examples**: Provide concrete before/after examples
|
||||
- **Tool support**: Offer automated migration scripts where possible
|
||||
- **Documentation**: Maintain comprehensive migration documentation
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### Legacy Version Not Found
|
||||
```
|
||||
LegacyVersionNotFoundError: Legacy version 'v1.0' not found for command 'query'
|
||||
```
|
||||
**Solution**: Register the legacy interface or check version identifier
|
||||
|
||||
#### Parameter Adaptation Failed
|
||||
```
|
||||
CompatibilityError: Legacy compatibility failed: unmapped parameter 'old_param'
|
||||
```
|
||||
**Solution**: Add parameter mapping to compatibility adapter
|
||||
|
||||
#### Git State Error
|
||||
```
|
||||
GitStateError: Git command failed: invalid commit hash
|
||||
```
|
||||
**Solution**: Verify git repository state and commit hash validity
|
||||
|
||||
#### Agent Task Failed
|
||||
```
|
||||
AgentTask execution failed: generate_migration_guide
|
||||
```
|
||||
**Solution**: Check agent configuration and ensure interfaces are properly registered
|
||||
|
||||
### Debugging Tools
|
||||
|
||||
```bash
|
||||
# Debug legacy registry
|
||||
markitect legacy debug registry --command=query
|
||||
|
||||
# Debug compatibility layer
|
||||
markitect legacy debug compatibility --command=query --version=v1.0
|
||||
|
||||
# Debug agent state
|
||||
markitect legacy debug agent --show-tasks --show-bindings
|
||||
|
||||
# Validate git bindings
|
||||
markitect legacy debug git-bindings --validate
|
||||
```
|
||||
|
||||
## Integration with Existing Systems
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# .github/workflows/legacy-management.yml
|
||||
name: Legacy Management
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 2 * * *' # Daily at 2 AM
|
||||
|
||||
jobs:
|
||||
legacy-maintenance:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v2
|
||||
- name: Run Legacy Agent
|
||||
run: |
|
||||
markitect legacy agent-maintenance
|
||||
markitect legacy generate-reports
|
||||
```
|
||||
|
||||
### Monitoring Integration
|
||||
|
||||
```python
|
||||
# Integration with monitoring systems
|
||||
def setup_legacy_monitoring():
|
||||
agent = LegacyAgent()
|
||||
|
||||
# Collect metrics
|
||||
stats = agent.get_agent_status()
|
||||
|
||||
# Send to monitoring system
|
||||
send_metric('legacy.interfaces.total', stats['registry_stats']['total_interfaces'])
|
||||
send_metric('legacy.tasks.pending', stats['tasks']['pending'])
|
||||
send_metric('legacy.usage.warnings', get_warning_count())
|
||||
```
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Planned Features
|
||||
|
||||
1. **Web Dashboard**: Visual interface for legacy management
|
||||
2. **API Integration**: REST API for programmatic access
|
||||
3. **Advanced Analytics**: Usage patterns and migration success tracking
|
||||
4. **Custom Workflows**: User-defined deprecation workflows
|
||||
5. **Plugin System**: Extensible compatibility adapters
|
||||
6. **Integration Tools**: IDE plugins for migration assistance
|
||||
|
||||
### Extension Points
|
||||
|
||||
The system is designed for extension:
|
||||
|
||||
- **Custom Adapters**: Implement specialized compatibility logic
|
||||
- **Agent Tasks**: Add custom automated tasks
|
||||
- **Transformers**: Create parameter and return value transformers
|
||||
- **Notification Systems**: Integrate with external notification platforms
|
||||
- **Migration Tools**: Build domain-specific migration assistants
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Legacy Compatibility System provides a comprehensive solution for managing CLI evolution while maintaining backward compatibility. By combining automated lifecycle management, precise version tracking, and intelligent compatibility adaptation, it enables smooth transitions between interface versions while providing users with clear migration paths and adequate time for adaptation.
|
||||
|
||||
The system's modular architecture allows for customization and extension while providing sensible defaults for common deprecation scenarios. With proper setup and configuration, it can significantly reduce the maintenance burden of supporting legacy interfaces while improving the user experience during transitions.
|
||||
488
guides/Layered_Architecture_GUIDE.md
Normal file
488
guides/Layered_Architecture_GUIDE.md
Normal file
@@ -0,0 +1,488 @@
|
||||
# MarkiTect Layered Architecture Blueprint
|
||||
|
||||
> **Strategic architectural guidance for evolving the MarkiTect codebase**
|
||||
|
||||
This document provides a comprehensive layered architecture blueprint based on the analysis of current capabilities and dependencies in the MarkiTect system. It serves as a roadmap for organizing and improving the codebase going forward.
|
||||
|
||||
## Executive Summary
|
||||
|
||||
MarkiTect demonstrates a sophisticated multi-domain system that has evolved organically. This blueprint formalizes the architecture into **7 distinct layers** with clear separation of concerns, dependency management, and scalability principles.
|
||||
|
||||
### Key Architectural Insights
|
||||
- **Current State**: Well-separated domains with some cross-cutting concerns
|
||||
- **Primary Pattern**: Hexagonal Architecture with Clean Architecture principles
|
||||
- **Growth Areas**: Plugin system, event-driven components, performance optimization
|
||||
- **Refactoring Priority**: Consolidate cross-cutting concerns, standardize interfaces
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Layered Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ PRESENTATION LAYER │
|
||||
│ (User Interface) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ APPLICATION LAYER │
|
||||
│ (Use Cases & Workflows) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ DOMAIN LAYER │
|
||||
│ (Business Logic) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ SERVICE LAYER │
|
||||
│ (Application Services) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ INFRASTRUCTURE LAYER │
|
||||
│ (Technical Capabilities) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ INTEGRATION LAYER │
|
||||
│ (External Systems) │
|
||||
├─────────────────────────────────────────────────────────────────┤
|
||||
│ FOUNDATION LAYER │
|
||||
│ (Core Technologies) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Layer-by-Layer Breakdown
|
||||
|
||||
### 🎯 Layer 1: Presentation Layer
|
||||
**Purpose**: User interface and interaction handling
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **CLI Framework** | `cli/core.py` | Command delegation, argument parsing | Application Layer |
|
||||
| **CLI Commands** | `cli/commands/` | Command implementations | Application Layer |
|
||||
| **Presenters** | `cli/presenters/` | Output formatting, view logic | None (top layer) |
|
||||
| **Formatters** | `cli/presenters/formatters.py` | Table/JSON/YAML output | None |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Single Responsibility**: Each presenter handles one output concern
|
||||
- ✅ **No Business Logic**: Pure presentation and formatting
|
||||
- 🔄 **Improvement Needed**: Standardize presenter interfaces
|
||||
|
||||
---
|
||||
|
||||
### 🚀 Layer 2: Application Layer
|
||||
**Purpose**: Use cases, workflows, and orchestration
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **Workspace Workflows** | `tddai/workspace.py` | TDD workflow orchestration | Domain + Service Layers |
|
||||
| **Issue Workflows** | `tddai/issue_creator.py` | Issue creation workflows | Domain + Integration Layers |
|
||||
| **Query Workflows** | `markitect/cli.py` | Database query orchestration | Service + Infrastructure |
|
||||
| **Cache Workflows** | `markitect/cache_service.py` | Caching orchestration | Infrastructure Layer |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Orchestration Focus**: Coordinates between layers without business logic
|
||||
- 🔄 **Improvement Needed**: Extract workflows from CLI commands
|
||||
- 🔄 **Standardization**: Consistent error handling patterns
|
||||
|
||||
---
|
||||
|
||||
### 🏛️ Layer 3: Domain Layer
|
||||
**Purpose**: Core business logic and domain models
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **Issue Models** | `domain/issues/models.py` | Issue lifecycle, label categorization | None (pure domain) |
|
||||
| **Project Models** | `domain/projects/models.py` | Project tracking, progress calculation | Issue Models |
|
||||
| **Issue Services** | `domain/issues/services.py` | Business rules, status determination | Issue Models |
|
||||
| **Project Services** | `domain/projects/services.py` | Project management logic | Project Models |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Pure Business Logic**: No infrastructure concerns
|
||||
- ✅ **Rich Domain Models**: Behavior embedded in entities
|
||||
- ✅ **Domain Services**: Complex business rules
|
||||
- 🔄 **Enhancement**: Add domain events for decoupling
|
||||
|
||||
---
|
||||
|
||||
### ⚙️ Layer 4: Service Layer
|
||||
**Purpose**: Application services and cross-cutting concerns
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **Document Service** | `markitect/document_manager.py` | Document lifecycle management | Infrastructure Layer |
|
||||
| **AST Service** | `markitect/ast_service.py` | AST processing coordination | Infrastructure Layer |
|
||||
| **Export Service** | `services/export_service.py` | Data export coordination | Infrastructure + Domain |
|
||||
| **Issue Service** | `services/issue_service.py` | Issue management coordination | Domain + Integration |
|
||||
| **Workspace Service** | `services/workspace_service.py` | Workspace management | Infrastructure Layer |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Coordination**: Orchestrates infrastructure and domain
|
||||
- 🔄 **Improvement Needed**: Extract from mixed locations
|
||||
- 🔄 **Standardization**: Consistent service interfaces
|
||||
|
||||
---
|
||||
|
||||
### 🔧 Layer 5: Infrastructure Layer
|
||||
**Purpose**: Technical capabilities and system resources
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **Database Management** | `markitect/database.py` | SQL database operations | Foundation Layer |
|
||||
| **AST Processing** | `markitect/parser.py` | Markdown parsing and AST generation | Foundation Layer |
|
||||
| **Cache Management** | `markitect/ast_cache.py` | File-based caching system | Foundation Layer |
|
||||
| **Configuration** | `config/` | System configuration management | Foundation Layer |
|
||||
| **Logging** | `infrastructure/logging/` | Structured logging system | Foundation Layer |
|
||||
| **Repositories** | `infrastructure/repositories/` | Data access abstractions | Foundation Layer |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Technical Focus**: No business logic
|
||||
- ✅ **Abstraction**: Clean interfaces for technical concerns
|
||||
- 🔄 **Consolidation**: Merge scattered infrastructure code
|
||||
|
||||
---
|
||||
|
||||
### 🌐 Layer 6: Integration Layer
|
||||
**Purpose**: External system integration and APIs
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **Gitea API Client** | `gitea/api_client.py` | HTTP API communication | Foundation Layer |
|
||||
| **Gitea Models** | `gitea/models.py` | External system data models | Foundation Layer |
|
||||
| **Git Integration** | `gitea/client.py` | Git platform abstraction | Foundation Layer |
|
||||
| **HTTP Client** | `gitea/http_client.py` | HTTP communication layer | Foundation Layer |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **External Focus**: Only external system concerns
|
||||
- ✅ **Adapter Pattern**: Translate external models to domain
|
||||
- 🔄 **Enhancement**: Plugin architecture for multiple platforms
|
||||
|
||||
---
|
||||
|
||||
### 🏢 Layer 7: Foundation Layer
|
||||
**Purpose**: Core technologies and utilities
|
||||
|
||||
| Component | Current Location | Capabilities | Dependencies |
|
||||
|-----------|------------------|--------------|--------------|
|
||||
| **SQLite Database** | System dependency | Data persistence | None |
|
||||
| **Python Runtime** | System dependency | Execution environment | None |
|
||||
| **File System** | System dependency | File operations | None |
|
||||
| **Network Stack** | System dependency | HTTP/API communication | None |
|
||||
| **Markdown-it** | External library | Markdown parsing engine | None |
|
||||
| **Core Utilities** | Various locations | Common functionality | None |
|
||||
|
||||
**Architectural Principles:**
|
||||
- ✅ **Stable Foundation**: Minimal change frequency
|
||||
- ✅ **Technology Choices**: Well-established libraries
|
||||
- 🔄 **Standardization**: Consistent utility patterns
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Capability Dependencies Map
|
||||
|
||||
### Core Dependency Flow
|
||||
```
|
||||
CLI Commands → Application Workflows → Domain Services → Infrastructure → Foundation
|
||||
↓ ↓ ↓ ↓
|
||||
Presenters Integration Layer Repository Layer System APIs
|
||||
```
|
||||
|
||||
### Cross-Cutting Concerns
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ Logging │ │ Configuration │ │ Caching │
|
||||
│ (All Layers) │ │ (All Layers) │ │ (Service+Infra) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
```
|
||||
|
||||
### Capability Interdependencies
|
||||
|
||||
| **Foundation Capabilities** | **Dependencies** |
|
||||
|------------------------------|------------------|
|
||||
| Database Storage | → Markdown Processing, Configuration |
|
||||
| AST Processing | → Performance Caching, Query Interface |
|
||||
| Configuration | → All system components |
|
||||
|
||||
| **Infrastructure Capabilities** | **Dependencies** |
|
||||
|----------------------------------|------------------|
|
||||
| Cache Management | → Database Storage, AST Processing |
|
||||
| Repository Abstraction | → Database Storage, External APIs |
|
||||
| Logging System | → Configuration Management |
|
||||
|
||||
| **Service Capabilities** | **Dependencies** |
|
||||
|---------------------------|------------------|
|
||||
| Document Management | → AST Processing, Cache Management |
|
||||
| Issue Management | → Git Integration, Database Storage |
|
||||
| Workspace Management | → Configuration, File System |
|
||||
|
||||
| **Application Capabilities** | **Dependencies** |
|
||||
|-------------------------------|------------------|
|
||||
| TDD Workflows | → Workspace Management, Issue Management |
|
||||
| Query Workflows | → Database Storage, Output Formatting |
|
||||
| CLI Operations | → All Service Layer capabilities |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Architectural Principles
|
||||
|
||||
### 1. **Dependency Direction**
|
||||
- **Rule**: Dependencies flow downward only
|
||||
- **Implementation**: Higher layers depend on lower layers, never reverse
|
||||
- **Benefit**: Prevents circular dependencies, enables testing
|
||||
|
||||
### 2. **Interface Segregation**
|
||||
- **Rule**: Small, focused interfaces
|
||||
- **Implementation**: Repository interfaces, service contracts
|
||||
- **Benefit**: Easier testing, cleaner implementations
|
||||
|
||||
### 3. **Single Responsibility**
|
||||
- **Rule**: Each component has one reason to change
|
||||
- **Implementation**: Separate concerns by layer and domain
|
||||
- **Benefit**: Maintainable, testable code
|
||||
|
||||
### 4. **Open/Closed Principle**
|
||||
- **Rule**: Open for extension, closed for modification
|
||||
- **Implementation**: Plugin architecture, strategy patterns
|
||||
- **Benefit**: New features without breaking existing code
|
||||
|
||||
### 5. **Configuration Over Convention**
|
||||
- **Rule**: Explicit configuration rather than implicit behavior
|
||||
- **Implementation**: Comprehensive configuration system
|
||||
- **Benefit**: Flexible deployment, clear behavior
|
||||
|
||||
---
|
||||
|
||||
## 📈 Migration Strategy
|
||||
|
||||
### Phase 1: Foundation Consolidation
|
||||
**Priority**: High | **Timeline**: 2-3 sprints
|
||||
|
||||
1. **Consolidate Utilities**
|
||||
- Extract common functionality to `foundation/` package
|
||||
- Standardize error handling patterns
|
||||
- Create consistent logging interfaces
|
||||
|
||||
2. **Standardize Infrastructure**
|
||||
- Consolidate repository implementations
|
||||
- Standardize configuration interfaces
|
||||
- Unify caching mechanisms
|
||||
|
||||
### Phase 2: Service Layer Extraction
|
||||
**Priority**: High | **Timeline**: 3-4 sprints
|
||||
|
||||
1. **Extract Application Services**
|
||||
- Move orchestration logic from CLI to service layer
|
||||
- Create consistent service interfaces
|
||||
- Implement dependency injection
|
||||
|
||||
2. **Standardize Domain Services**
|
||||
- Ensure pure business logic in domain layer
|
||||
- Add domain events for decoupling
|
||||
- Create domain service contracts
|
||||
|
||||
### Phase 3: Presentation Enhancement
|
||||
**Priority**: Medium | **Timeline**: 2-3 sprints
|
||||
|
||||
1. **Standardize Presenters**
|
||||
- Create presenter interface contracts
|
||||
- Implement consistent error handling
|
||||
- Add format validation
|
||||
|
||||
2. **Enhance CLI Framework**
|
||||
- Improve command delegation
|
||||
- Add middleware support
|
||||
- Implement plugin hooks
|
||||
|
||||
### Phase 4: Integration Expansion
|
||||
**Priority**: Medium | **Timeline**: 3-4 sprints
|
||||
|
||||
1. **Plugin Architecture**
|
||||
- Design plugin interface
|
||||
- Implement plugin discovery
|
||||
- Add GitHub/GitLab adapters
|
||||
|
||||
2. **Event System**
|
||||
- Implement domain events
|
||||
- Add event handlers
|
||||
- Create async processing
|
||||
|
||||
---
|
||||
|
||||
## 🚧 Implementation Guidelines
|
||||
|
||||
### Directory Structure Recommendation
|
||||
```
|
||||
markitect/
|
||||
├── foundation/ # Layer 7: Core utilities and constants
|
||||
│ ├── exceptions.py
|
||||
│ ├── types.py
|
||||
│ └── utilities.py
|
||||
├── infrastructure/ # Layer 5: Technical capabilities
|
||||
│ ├── database/
|
||||
│ ├── caching/
|
||||
│ ├── configuration/
|
||||
│ └── logging/
|
||||
├── integration/ # Layer 6: External systems
|
||||
│ ├── gitea/
|
||||
│ ├── github/ # Future
|
||||
│ └── plugins/ # Future
|
||||
├── domain/ # Layer 3: Business logic
|
||||
│ ├── issues/
|
||||
│ ├── projects/
|
||||
│ └── documents/ # Future
|
||||
├── services/ # Layer 4: Application services
|
||||
│ ├── document_service.py
|
||||
│ ├── issue_service.py
|
||||
│ └── workspace_service.py
|
||||
├── application/ # Layer 2: Use cases and workflows
|
||||
│ ├── workflows/
|
||||
│ └── use_cases/
|
||||
└── presentation/ # Layer 1: User interfaces
|
||||
├── cli/
|
||||
├── api/ # Future
|
||||
└── web/ # Future
|
||||
```
|
||||
|
||||
### Coding Standards
|
||||
|
||||
#### Interface Design
|
||||
```python
|
||||
# Good: Clear interface with single responsibility
|
||||
class DocumentRepository(Protocol):
|
||||
def save(self, document: Document) -> DocumentId: ...
|
||||
def find_by_id(self, id: DocumentId) -> Optional[Document]: ...
|
||||
def find_all(self) -> List[Document]: ...
|
||||
|
||||
# Avoid: Large interfaces mixing concerns
|
||||
class MegaRepository(Protocol):
|
||||
def save_document(self, doc): ...
|
||||
def save_issue(self, issue): ...
|
||||
def send_email(self, msg): ... # Wrong layer!
|
||||
```
|
||||
|
||||
#### Dependency Injection
|
||||
```python
|
||||
# Good: Constructor injection with interfaces
|
||||
class DocumentService:
|
||||
def __init__(
|
||||
self,
|
||||
repository: DocumentRepository,
|
||||
cache: CacheService,
|
||||
logger: Logger
|
||||
):
|
||||
self._repository = repository
|
||||
self._cache = cache
|
||||
self._logger = logger
|
||||
|
||||
# Avoid: Direct instantiation
|
||||
class DocumentService:
|
||||
def __init__(self):
|
||||
self._repository = SqliteDocumentRepository() # Tight coupling
|
||||
```
|
||||
|
||||
#### Error Handling
|
||||
```python
|
||||
# Good: Domain-specific exceptions
|
||||
class DocumentNotFoundError(DomainException):
|
||||
def __init__(self, document_id: DocumentId):
|
||||
super().__init__(f"Document {document_id} not found")
|
||||
|
||||
# Avoid: Generic exceptions
|
||||
raise Exception("Something went wrong") # Too generic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Quality Metrics
|
||||
|
||||
### Architectural Health Indicators
|
||||
|
||||
| **Metric** | **Current State** | **Target State** | **Priority** |
|
||||
|------------|-------------------|------------------|--------------|
|
||||
| **Cyclomatic Complexity** | Mixed (2-15) | < 10 per method | High |
|
||||
| **Dependency Depth** | 3-5 levels | < 4 levels | Medium |
|
||||
| **Interface Coupling** | Tight in some areas | Loose coupling | High |
|
||||
| **Test Coverage** | 95%+ | Maintain 95%+ | Medium |
|
||||
| **Module Cohesion** | Good in domain | High cohesion | Medium |
|
||||
|
||||
### Code Quality Targets
|
||||
|
||||
1. **Maintainability Index**: > 80
|
||||
2. **Lines of Code per Method**: < 20
|
||||
3. **Parameters per Method**: < 5
|
||||
4. **Nested Depth**: < 3 levels
|
||||
5. **Documentation Coverage**: > 90%
|
||||
|
||||
---
|
||||
|
||||
## 🔮 Future Evolution Path
|
||||
|
||||
### Short Term (1-2 releases)
|
||||
- ✅ **Foundation Layer**: Consolidate utilities and infrastructure
|
||||
- ✅ **Service Layer**: Extract and standardize application services
|
||||
- ✅ **Interface Standardization**: Create consistent contracts
|
||||
|
||||
### Medium Term (3-5 releases)
|
||||
- 🚀 **Plugin Architecture**: Support multiple Git platforms
|
||||
- 🚀 **Event System**: Implement domain events and handlers
|
||||
- 🚀 **API Layer**: Add REST API for external integration
|
||||
|
||||
### Long Term (6+ releases)
|
||||
- 🌟 **Microservices**: Split into focused services if needed
|
||||
- 🌟 **Event Sourcing**: Consider for audit and replay capabilities
|
||||
- 🌟 **Multi-tenant**: Support multiple organizations/teams
|
||||
|
||||
---
|
||||
|
||||
## 📝 Decision Records
|
||||
|
||||
### ADR-001: Layered Architecture Adoption
|
||||
**Status**: Proposed | **Date**: 2025-09-29
|
||||
|
||||
**Context**: MarkiTect has grown organically with mixed architectural patterns.
|
||||
|
||||
**Decision**: Adopt 7-layer architecture with clear separation of concerns.
|
||||
|
||||
**Consequences**:
|
||||
- ✅ Improved maintainability and testability
|
||||
- ✅ Clear dependency management
|
||||
- ⚠️ Requires refactoring effort
|
||||
- ⚠️ Learning curve for new patterns
|
||||
|
||||
### ADR-002: Domain-Driven Design Principles
|
||||
**Status**: Proposed | **Date**: 2025-09-29
|
||||
|
||||
**Context**: Business logic is scattered across layers.
|
||||
|
||||
**Decision**: Implement DDD with rich domain models and pure business logic.
|
||||
|
||||
**Consequences**:
|
||||
- ✅ Business logic centralized and testable
|
||||
- ✅ Domain experts can understand code
|
||||
- ⚠️ Requires domain modeling effort
|
||||
|
||||
### ADR-003: Plugin Architecture for External Systems
|
||||
**Status**: Proposed | **Date**: 2025-09-29
|
||||
|
||||
**Context**: Current tight coupling to Gitea limits platform support.
|
||||
|
||||
**Decision**: Implement plugin architecture for Git platform integration.
|
||||
|
||||
**Consequences**:
|
||||
- ✅ Support multiple platforms (GitHub, GitLab, etc.)
|
||||
- ✅ Community can add new integrations
|
||||
- ⚠️ Additional complexity in interface design
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Success Criteria
|
||||
|
||||
### Technical Metrics
|
||||
- [ ] **Dependency Violations**: Zero upward dependencies
|
||||
- [ ] **Test Coverage**: Maintain > 95% coverage
|
||||
- [ ] **Build Time**: < 30 seconds for full test suite
|
||||
- [ ] **Documentation**: All public APIs documented
|
||||
|
||||
### Business Metrics
|
||||
- [ ] **Feature Velocity**: Reduce time-to-market for new features
|
||||
- [ ] **Bug Rate**: < 1 bug per 1000 lines of code
|
||||
- [ ] **Developer Onboarding**: New developers productive in < 1 week
|
||||
- [ ] **Platform Support**: Support 3+ Git platforms
|
||||
|
||||
---
|
||||
|
||||
*This architecture blueprint is a living document that should evolve with the system. Regular reviews and updates ensure it remains relevant and valuable for development decisions.*
|
||||
423
guides/Test_Optimization_GUIDE.md
Normal file
423
guides/Test_Optimization_GUIDE.md
Normal file
@@ -0,0 +1,423 @@
|
||||
# MarkiTect Test Architecture & Execution Strategy
|
||||
|
||||
> **Architectural test organization and reverse dependency execution order**
|
||||
|
||||
This document defines the test architecture based on the 7-layer system architecture, establishing clear naming conventions and optimal execution order for faster feedback and reduced debugging time.
|
||||
|
||||
## 🏗️ Test Architecture Mapping
|
||||
|
||||
### Layer-Based Test Organization
|
||||
|
||||
Tests are organized by architectural layer with execution order optimized for dependency flow:
|
||||
|
||||
```
|
||||
Test Execution Order (Foundation → Presentation):
|
||||
Foundation → Infrastructure → Integration → Domain → Service → Application → Presentation
|
||||
↑ ↑ ↑ ↑ ↑ ↑ ↑
|
||||
Fastest Cache Tests Gitea API Business Service Workflows CLI Tests
|
||||
Feedback DB Tests Tests Logic Tests Tests E2E Tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Current Test Files → New Architecture Mapping
|
||||
|
||||
### **Layer 7: Foundation Tests** (Execute First - Fastest Feedback)
|
||||
*Core technology and utility validation*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `test_parser.py` | `test_l7_foundation_markdown_parsing.py` | Core markdown parsing engine | **1** |
|
||||
| `test_issue_1_database_initialization.py` | `test_l7_foundation_database_core.py` | SQLite database initialization | **2** |
|
||||
|
||||
**Rationale**: Foundation layer failures break everything downstream. Test these first for immediate feedback.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 5: Infrastructure Tests** (Execute Second - Core Systems)
|
||||
*Technical capabilities and system resources*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `test_issue_2_file_ingestion.py` | `test_l5_infrastructure_ast_processing.py` | AST processing and caching | **3** |
|
||||
| `test_issue_13_cache_commands.py` | `test_l5_infrastructure_cache_management.py` | Cache system operations | **4** |
|
||||
| `test_issue_13_cache_info_command.py` | `test_l5_infrastructure_cache_monitoring.py` | Cache statistics and monitoring | **5** |
|
||||
| `test_issue_14_query_commands.py` | `test_l5_infrastructure_database_queries.py` | Database query interface | **6** |
|
||||
| `test_config_cli_commands.py` | `test_l5_infrastructure_configuration.py` | Configuration management | **7** |
|
||||
| `unit/infrastructure/test_testing_infrastructure.py` | `test_l5_infrastructure_test_framework.py` | Testing infrastructure | **8** |
|
||||
|
||||
**Rationale**: Infrastructure provides technical foundation for all business logic. Failures here cascade widely.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 6: Integration Tests** (Execute Third - External Dependencies)
|
||||
*External system integration and APIs*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `test_gitea_facade.py` | `test_l6_integration_gitea_api.py` | Gitea API client functionality | **9** |
|
||||
| `test_issue_creator.py` | `test_l6_integration_issue_creation.py` | Issue creation via external APIs | **10** |
|
||||
|
||||
**Rationale**: Integration failures are often environmental. Test after core systems are validated.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 3: Domain Tests** (Execute Fourth - Business Logic)
|
||||
*Pure business logic validation*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `unit/domain/issues/test_issue_models.py` | `test_l3_domain_issue_models.py` | Issue domain models and business rules | **11** |
|
||||
| `unit/domain/issues/test_issue_services.py` | `test_l3_domain_issue_services.py` | Issue business logic services | **12** |
|
||||
| `unit/domain/projects/test_project_models.py` | `test_l3_domain_project_models.py` | Project domain models and logic | **13** |
|
||||
| `e2e/performance/test_domain_performance.py` | `test_l3_domain_performance_validation.py` | Domain logic performance characteristics | **14** |
|
||||
|
||||
**Rationale**: Domain logic is independent of technical concerns. Test after infrastructure is stable.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 4: Service Tests** (Execute Fifth - Application Services)
|
||||
*Cross-cutting concerns and service coordination*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `test_issue_4_retrieve_all_files.py` | `test_l4_service_document_management.py` | Document service operations | **15** |
|
||||
| `test_issue_2_get_modify_commands.py` | `test_l4_service_document_modification.py` | Document modification services | **16** |
|
||||
| `test_issue_15_ast_commands.py` | `test_l4_service_ast_analysis.py` | AST analysis services | **17** |
|
||||
| `test_issue_14_output_formatting.py` | `test_l4_service_output_formatting.py` | Output formatting services | **18** |
|
||||
|
||||
**Rationale**: Services coordinate domain and infrastructure. Test after both layers are stable.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 2: Application Tests** (Execute Sixth - Use Cases & Workflows)
|
||||
*Workflow orchestration and use case validation*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `test_issue_11_workspace_creation.py` | `test_l2_application_workspace_workflows.py` | TDD workspace management workflows | **19** |
|
||||
| `test_issue_11_workspace_creation_validation.py` | `test_l2_application_workspace_validation.py` | Workspace workflow validation | **20** |
|
||||
| `test_issue_11_workflow_integration.py` | `test_l2_application_tdd_workflows.py` | Complete TDD workflow integration | **21** |
|
||||
| `test_issue_11_feature.py` | `test_l2_application_feature_workflows.py` | Feature development workflows | **22** |
|
||||
|
||||
**Rationale**: Applications orchestrate multiple services. Test after service layer is validated.
|
||||
|
||||
---
|
||||
|
||||
### **Layer 1: Presentation Tests** (Execute Last - User Interface)
|
||||
*CLI and user interaction validation*
|
||||
|
||||
| Current Test File | New Test File | Test Focus | Execution Priority |
|
||||
|-------------------|---------------|------------|-------------------|
|
||||
| `e2e/cli/test_issue_commands_e2e.py` | `test_l1_presentation_cli_interface.py` | End-to-end CLI command testing | **23** |
|
||||
|
||||
**Rationale**: Presentation layer depends on all other layers. Test last for comprehensive integration validation.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Test Execution Configuration
|
||||
|
||||
### Reverse Dependency Order Execution
|
||||
|
||||
```bash
|
||||
# Execute in dependency order for optimal feedback
|
||||
pytest tests/test_l7_foundation_*.py # Foundation (fastest)
|
||||
pytest tests/test_l5_infrastructure_*.py # Infrastructure
|
||||
pytest tests/test_l6_integration_*.py # Integration
|
||||
pytest tests/test_l3_domain_*.py # Domain
|
||||
pytest tests/test_l4_service_*.py # Service
|
||||
pytest tests/test_l2_application_*.py # Application
|
||||
pytest tests/test_l1_presentation_*.py # Presentation (slowest)
|
||||
```
|
||||
|
||||
### pytest.ini Configuration
|
||||
|
||||
Create optimized test execution configuration:
|
||||
|
||||
```ini
|
||||
[tool:pytest]
|
||||
testpaths = tests
|
||||
python_files = test_*.py
|
||||
python_classes = Test*
|
||||
python_functions = test_*
|
||||
|
||||
# Test execution order optimization
|
||||
collect_ignore = ["setup.py"]
|
||||
addopts =
|
||||
--strict-markers
|
||||
--strict-config
|
||||
--verbose
|
||||
--tb=short
|
||||
--durations=10
|
||||
|
||||
# Custom test execution order
|
||||
markers =
|
||||
foundation: Foundation layer tests (execute first)
|
||||
infrastructure: Infrastructure layer tests
|
||||
integration: Integration layer tests
|
||||
domain: Domain layer tests
|
||||
service: Service layer tests
|
||||
application: Application layer tests
|
||||
presentation: Presentation layer tests (execute last)
|
||||
slow: Slow tests requiring longer timeout
|
||||
performance: Performance validation tests
|
||||
```
|
||||
|
||||
### Custom Test Runner Script
|
||||
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Architectural test runner with dependency-optimized execution order.
|
||||
"""
|
||||
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
def run_layer_tests(layer_name: str, pattern: str) -> bool:
|
||||
"""Run tests for a specific architectural layer."""
|
||||
print(f"\n🧪 Testing {layer_name} Layer...")
|
||||
print("=" * 50)
|
||||
|
||||
cmd = [
|
||||
"python", "-m", "pytest",
|
||||
f"tests/{pattern}",
|
||||
"-v", "--tb=short",
|
||||
f"--durations=5"
|
||||
]
|
||||
|
||||
result = subprocess.run(cmd)
|
||||
success = result.returncode == 0
|
||||
|
||||
if success:
|
||||
print(f"✅ {layer_name} layer tests PASSED")
|
||||
else:
|
||||
print(f"❌ {layer_name} layer tests FAILED")
|
||||
|
||||
return success
|
||||
|
||||
def main():
|
||||
"""Execute tests in reverse dependency order."""
|
||||
layers = [
|
||||
("Foundation", "test_l7_foundation_*.py"),
|
||||
("Infrastructure", "test_l5_infrastructure_*.py"),
|
||||
("Integration", "test_l6_integration_*.py"),
|
||||
("Domain", "test_l3_domain_*.py"),
|
||||
("Service", "test_l4_service_*.py"),
|
||||
("Application", "test_l2_application_*.py"),
|
||||
("Presentation", "test_l1_presentation_*.py")
|
||||
]
|
||||
|
||||
print("🏗️ MarkiTect Architectural Test Runner")
|
||||
print("Executing tests in reverse dependency order...")
|
||||
|
||||
failed_layers = []
|
||||
|
||||
for layer_name, pattern in layers:
|
||||
if not run_layer_tests(layer_name, pattern):
|
||||
failed_layers.append(layer_name)
|
||||
print(f"\n⚠️ Stopping at {layer_name} layer failure")
|
||||
break
|
||||
|
||||
if failed_layers:
|
||||
print(f"\n❌ Test execution stopped at layer: {failed_layers[0]}")
|
||||
print("Fix foundation issues before testing dependent layers.")
|
||||
sys.exit(1)
|
||||
else:
|
||||
print("\n✅ All architectural layers passed!")
|
||||
print("🎉 System is architecturally sound!")
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Test Execution Benefits
|
||||
|
||||
### Performance Optimization
|
||||
|
||||
| **Strategy** | **Time Savings** | **Debugging Efficiency** |
|
||||
|-------------|-------------------|---------------------------|
|
||||
| **Foundation First** | 60-80% faster feedback | Fix root causes immediately |
|
||||
| **Layer Isolation** | 40-60% reduced test time | Clear failure boundaries |
|
||||
| **Dependency Order** | 70-90% fewer cascade failures | Targeted fixes |
|
||||
| **Early Termination** | 80%+ time saved on foundation failures | Stop at first architectural break |
|
||||
|
||||
### Development Workflow Benefits
|
||||
|
||||
1. **Immediate Feedback**: Foundation failures caught in < 5 seconds
|
||||
2. **Targeted Debugging**: Clear layer-specific failure isolation
|
||||
3. **Reduced Context Switching**: Fix architectural layers systematically
|
||||
4. **Confidence Building**: Green foundation = stable architecture
|
||||
5. **Parallel Development**: Teams can work on different layers safely
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Migration Plan
|
||||
|
||||
### Phase 1: Test File Renaming (1-2 days)
|
||||
|
||||
```bash
|
||||
# Foundation Layer
|
||||
mv test_parser.py test_l7_foundation_markdown_parsing.py
|
||||
mv test_issue_1_database_initialization.py test_l7_foundation_database_core.py
|
||||
|
||||
# Infrastructure Layer
|
||||
mv test_issue_2_file_ingestion.py test_l5_infrastructure_ast_processing.py
|
||||
mv test_issue_13_cache_commands.py test_l5_infrastructure_cache_management.py
|
||||
mv test_config_cli_commands.py test_l5_infrastructure_configuration.py
|
||||
|
||||
# Integration Layer
|
||||
mv test_gitea_facade.py test_l6_integration_gitea_api.py
|
||||
mv test_issue_creator.py test_l6_integration_issue_creation.py
|
||||
|
||||
# Domain Layer
|
||||
mv unit/domain/issues/test_issue_models.py test_l3_domain_issue_models.py
|
||||
mv unit/domain/issues/test_issue_services.py test_l3_domain_issue_services.py
|
||||
mv unit/domain/projects/test_project_models.py test_l3_domain_project_models.py
|
||||
|
||||
# Service Layer
|
||||
mv test_issue_4_retrieve_all_files.py test_l4_service_document_management.py
|
||||
mv test_issue_15_ast_commands.py test_l4_service_ast_analysis.py
|
||||
|
||||
# Application Layer
|
||||
mv test_issue_11_workspace_creation.py test_l2_application_workspace_workflows.py
|
||||
mv test_issue_11_workflow_integration.py test_l2_application_tdd_workflows.py
|
||||
|
||||
# Presentation Layer
|
||||
mv e2e/cli/test_issue_commands_e2e.py test_l1_presentation_cli_interface.py
|
||||
```
|
||||
|
||||
### Phase 2: Test Configuration Setup (1 day)
|
||||
|
||||
1. Update `pytest.ini` with execution order markers
|
||||
2. Create architectural test runner script
|
||||
3. Update CI/CD pipeline configuration
|
||||
4. Create test execution documentation
|
||||
|
||||
### Phase 3: Team Training (1 day)
|
||||
|
||||
1. Document new test architecture
|
||||
2. Train team on execution strategy
|
||||
3. Update development workflow docs
|
||||
4. Create architectural test guidelines
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Quality Gates
|
||||
|
||||
### Layer-Specific Quality Requirements
|
||||
|
||||
| **Layer** | **Coverage Target** | **Performance Target** | **Failure Rate Target** |
|
||||
|-----------|-------------------|------------------------|-------------------------|
|
||||
| **Foundation** | 98%+ | < 5s execution | < 0.1% failure rate |
|
||||
| **Infrastructure** | 95%+ | < 15s execution | < 0.5% failure rate |
|
||||
| **Integration** | 85%+ | < 30s execution | < 2% failure rate |
|
||||
| **Domain** | 98%+ | < 10s execution | < 0.2% failure rate |
|
||||
| **Service** | 90%+ | < 20s execution | < 1% failure rate |
|
||||
| **Application** | 85%+ | < 45s execution | < 2% failure rate |
|
||||
| **Presentation** | 80%+ | < 60s execution | < 5% failure rate |
|
||||
|
||||
### Architectural Health Metrics
|
||||
|
||||
1. **Foundation Stability**: > 99.5% pass rate
|
||||
2. **Layer Isolation**: Zero upward dependency failures
|
||||
3. **Execution Time**: < 3 minutes for full architectural test suite
|
||||
4. **Debugging Efficiency**: Average fix time < 15 minutes per layer
|
||||
|
||||
---
|
||||
|
||||
## 📝 Architectural Test Patterns
|
||||
|
||||
### Foundation Layer Pattern
|
||||
```python
|
||||
# test_l7_foundation_markdown_parsing.py
|
||||
class TestFoundationMarkdownParsing:
|
||||
"""Foundation layer: Core markdown parsing engine validation."""
|
||||
|
||||
def test_markdown_parser_converts_heading_and_paragraph_to_ast_tokens(self):
|
||||
"""FOUNDATION: Validate core parsing capability."""
|
||||
# Fast, isolated, no dependencies
|
||||
```
|
||||
|
||||
### Infrastructure Layer Pattern
|
||||
```python
|
||||
# test_l5_infrastructure_cache_management.py
|
||||
class TestInfrastructureCacheManagement:
|
||||
"""Infrastructure layer: Cache system technical capabilities."""
|
||||
|
||||
def test_cache_info_command_works_with_empty_and_populated_cache(self):
|
||||
"""INFRASTRUCTURE: Validate cache system operations."""
|
||||
# Technical capability, depends on foundation
|
||||
```
|
||||
|
||||
### Domain Layer Pattern
|
||||
```python
|
||||
# test_l3_domain_issue_models.py
|
||||
class TestDomainIssueModels:
|
||||
"""Domain layer: Pure business logic validation."""
|
||||
|
||||
def test_issue_creation_with_valid_data(self):
|
||||
"""DOMAIN: Validate business rules and logic."""
|
||||
# No infrastructure dependencies, pure logic
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚦 Continuous Integration Integration
|
||||
|
||||
### GitHub Actions Workflow
|
||||
|
||||
```yaml
|
||||
name: Architectural Test Suite
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
architectural-tests:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: '3.12'
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install -r requirements.txt
|
||||
pip install -r requirements-test.txt
|
||||
|
||||
- name: Run Foundation Tests (Layer 7)
|
||||
run: pytest tests/test_l7_foundation_*.py -v
|
||||
|
||||
- name: Run Infrastructure Tests (Layer 5)
|
||||
run: pytest tests/test_l5_infrastructure_*.py -v
|
||||
if: success()
|
||||
|
||||
- name: Run Integration Tests (Layer 6)
|
||||
run: pytest tests/test_l6_integration_*.py -v
|
||||
if: success()
|
||||
|
||||
- name: Run Domain Tests (Layer 3)
|
||||
run: pytest tests/test_l3_domain_*.py -v
|
||||
if: success()
|
||||
|
||||
- name: Run Service Tests (Layer 4)
|
||||
run: pytest tests/test_l4_service_*.py -v
|
||||
if: success()
|
||||
|
||||
- name: Run Application Tests (Layer 2)
|
||||
run: pytest tests/test_l2_application_*.py -v
|
||||
if: success()
|
||||
|
||||
- name: Run Presentation Tests (Layer 1)
|
||||
run: pytest tests/test_l1_presentation_*.py -v
|
||||
if: success()
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*This architectural test strategy transforms testing from a time-consuming bottleneck into a fast, targeted debugging tool that respects system architecture and optimizes developer productivity.*
|
||||
71
guides/Working_With_Issues_GUIDE.md
Normal file
71
guides/Working_With_Issues_GUIDE.md
Normal file
@@ -0,0 +1,71 @@
|
||||
# Issue Management Workflow Reminder
|
||||
|
||||
## 🎯 CRITICAL REMINDER: Gitea is the Source of Truth
|
||||
|
||||
**PRIMARY RULE**: When discussing issues for assessment, feasibility evaluation, prioritization, or implementation planning, ALWAYS fetch the issue directly from Gitea.
|
||||
|
||||
## When to Fetch from Gitea
|
||||
|
||||
### ✅ Always Fetch from Gitea When:
|
||||
- Assessing feasibility of an issue
|
||||
- Deciding if we should implement an issue next
|
||||
- Refining issue requirements or scope
|
||||
- Evaluating whether to drop an issue
|
||||
- Discussing implementation strategy
|
||||
- Planning issue priority
|
||||
- Issue is not currently in the working directory
|
||||
- Issue has been implemented before but needs review
|
||||
|
||||
### ⚠️ Local Files Are Insufficient For:
|
||||
- Issue assessment discussions
|
||||
- Implementation planning
|
||||
- Priority evaluation
|
||||
- Scope refinement
|
||||
- Feasibility analysis
|
||||
|
||||
## Source of Truth Hierarchy
|
||||
|
||||
1. **Gitea Repository** - Primary datastore for all issues
|
||||
2. **Working Directory** - Only for issues currently being implemented
|
||||
3. **Local Index/Cache** - For quick reference only, not decision-making
|
||||
|
||||
## Proper Workflow
|
||||
|
||||
```bash
|
||||
# When discussing Issue #46 (or any issue number):
|
||||
1. Use WebFetch or GitLab/Gitea tools to fetch the live issue
|
||||
2. Read the current state, comments, and requirements
|
||||
3. Base all decisions on the live Gitea data
|
||||
4. Do NOT rely on local files, cached data, or assumptions
|
||||
```
|
||||
|
||||
## Implementation Commands
|
||||
|
||||
```bash
|
||||
# ✅ WORKING: Use existing Makefile targets
|
||||
make show-issue NUM=46 # Show detailed issue #46
|
||||
make list-issues # List all issues with status
|
||||
make list-open-issues # Show only open issues
|
||||
|
||||
# ✅ WORKING: Export for analysis
|
||||
make issues-get # Export compact TSV to ISSUES.index
|
||||
make issues-json # Export all issues as JSON
|
||||
make issues-csv # Export as CSV for spreadsheet analysis
|
||||
make issues-high # Export only high/critical priority
|
||||
|
||||
# ❌ NOT AVAILABLE: These require additional tools
|
||||
gh issue view 46 --repo your-repo
|
||||
WebFetch "https://gitea-instance/repo/issues/46" # (certificate issues)
|
||||
```
|
||||
|
||||
## Why This Matters
|
||||
|
||||
- **Accuracy**: Issues may have been updated, refined, or closed
|
||||
- **Completeness**: Comments and discussions provide crucial context
|
||||
- **Current State**: Status, labels, and priority may have changed
|
||||
- **Team Collaboration**: Other team members may have added insights
|
||||
- **Implementation History**: Previous attempts or decisions are documented
|
||||
|
||||
---
|
||||
|
||||
**🚨 REMINDER TO CLAUDE**: Before discussing any issue assessment, feasibility, or planning, ALWAYS fetch the issue from Gitea first. Local files are NOT sufficient for decision-making about issues.
|
||||
Reference in New Issue
Block a user