prompt_manager 0.5.7 → 0.5.8

data/docs/development/contributing.md

@@ -0,0 +1,425 @@
+# Contributing to PromptManager
+
+Thank you for your interest in contributing to PromptManager! This guide will help you get started with contributing to the project.
+
+## Getting Started
+
+### Prerequisites
+
+- Ruby 3.0 or higher
+- Git
+- A GitHub account
+
+### Development Setup
+
+1. **Fork the repository** on GitHub
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/prompt_manager.git
+   cd prompt_manager
+   ```
+
+3. **Install dependencies**:
+   ```bash
+   bundle install
+   ```
+
+4. **Run the tests** to ensure everything is working:
+   ```bash
+   bundle exec rspec
+   ```
+
+5. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development Workflow
+
+### Code Style
+
+We follow standard Ruby conventions and use RuboCop for code style enforcement:
+
+```bash
+# Check code style
+bundle exec rubocop
+
+# Auto-fix style issues
+bundle exec rubocop -a
+```
+
+### Testing
+
+We use RSpec for testing. Please ensure all tests pass and add tests for new features:
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test file
+bundle exec rspec spec/prompt_spec.rb
+
+# Run tests with coverage
+COVERAGE=true bundle exec rspec
+```
+
+### Test Coverage
+
+We aim for high test coverage. Check coverage after running tests:
+
+```bash
+open coverage/index.html  # macOS
+xdg-open coverage/index.html  # Linux
+```
+
+## Making Changes
+
+### Adding New Features
+
+1. **Create an issue** first to discuss the feature
+2. **Write tests** for your feature (TDD approach preferred)
+3. **Implement the feature** with clear, readable code
+4. **Update documentation** as needed
+5. **Ensure all tests pass**
+
+### Bug Fixes
+
+1. **Create a failing test** that reproduces the bug
+2. **Fix the bug** with minimal changes
+3. **Ensure the test now passes**
+4. **Check for any regressions**
+
+### Example: Adding a New Storage Adapter
+
+```ruby
+# 1. Create the adapter class
+class MyCustomAdapter < PromptManager::Storage::Base
+  def read(prompt_id)
+    # Implementation
+  end
+  
+  def write(prompt_id, content)
+    # Implementation
+  end
+  
+  # ... other required methods
+end
+
+# 2. Add comprehensive tests
+RSpec.describe MyCustomAdapter do
+  let(:adapter) { described_class.new(config_options) }
+  
+  include_examples 'a storage adapter'
+  
+  describe 'custom functionality' do
+    it 'handles specific use case' do
+      # Test implementation
+    end
+  end
+end
+
+# 3. Update documentation
+# Add to docs/storage/custom-adapters.md
+```
+
+## Code Guidelines
+
+### Ruby Style Guide
+
+- Use 2 spaces for indentation
+- Follow Ruby naming conventions (snake_case for methods and variables)
+- Keep line length under 100 characters
+- Use descriptive method and variable names
+- Add comments for complex logic
+
+### Architecture Principles
+
+- **Single Responsibility**: Each class should have one clear purpose
+- **Open/Closed**: Open for extension, closed for modification
+- **Dependency Injection**: Avoid hard dependencies, use dependency injection
+- **Error Handling**: Handle errors gracefully with meaningful messages
+
+### Example Code Structure
+
+```ruby
+module PromptManager
+  module Storage
+    class CustomAdapter < Base
+      # Clear initialization with validation
+      def initialize(connection_string:, **options)
+        validate_connection_string(connection_string)
+        @connection = establish_connection(connection_string)
+        super(**options)
+      end
+      
+      # Clear method responsibilities
+      def read(prompt_id)
+        validate_prompt_id(prompt_id)
+        
+        result = @connection.get(key_for(prompt_id))
+        raise PromptNotFoundError.new("Prompt '#{prompt_id}' not found") unless result
+        
+        result
+      rescue ConnectionError => e
+        raise StorageError.new("Connection failed: #{e.message}")
+      end
+      
+      private
+      
+      # Helper methods are private and focused
+      def validate_prompt_id(prompt_id)
+        raise ArgumentError, 'prompt_id cannot be nil' if prompt_id.nil?
+        raise ArgumentError, 'prompt_id cannot be empty' if prompt_id.empty?
+      end
+      
+      def key_for(prompt_id)
+        "prompts:#{prompt_id}"
+      end
+    end
+  end
+end
+```
+
+## Testing Guidelines
+
+### Test Structure
+
+```ruby
+RSpec.describe PromptManager::Prompt do
+  # Use let blocks for test setup
+  let(:prompt_id) { 'test_prompt' }
+  let(:storage) { instance_double(PromptManager::Storage::Base) }
+  let(:prompt) { described_class.new(id: prompt_id, storage: storage) }
+  
+  describe '#render' do
+    context 'when prompt exists' do
+      before do
+        allow(storage).to receive(:read)
+          .with(prompt_id)
+          .and_return('Hello [NAME]!')
+      end
+      
+      it 'renders with parameters' do
+        result = prompt.render(name: 'World')
+        expect(result).to eq 'Hello World!'
+      end
+      
+      it 'handles missing parameters gracefully' do
+        expect {
+          prompt.render
+        }.to raise_error(PromptManager::MissingParametersError)
+      end
+    end
+    
+    context 'when prompt does not exist' do
+      before do
+        allow(storage).to receive(:read)
+          .with(prompt_id)
+          .and_raise(PromptManager::PromptNotFoundError)
+      end
+      
+      it 'raises PromptNotFoundError' do
+        expect {
+          prompt.render
+        }.to raise_error(PromptManager::PromptNotFoundError)
+      end
+    end
+  end
+end
+```
+
+### Shared Examples
+
+Use shared examples for common behavior:
+
+```ruby
+# spec/support/shared_examples/storage_adapter.rb
+RSpec.shared_examples 'a storage adapter' do
+  describe 'required interface' do
+    it 'implements read method' do
+      expect(adapter).to respond_to(:read)
+    end
+    
+    it 'implements write method' do
+      expect(adapter).to respond_to(:write)
+    end
+    
+    it 'implements exist? method' do
+      expect(adapter).to respond_to(:exist?)
+    end
+  end
+  
+  describe 'basic functionality' do
+    let(:prompt_id) { 'test_prompt' }
+    let(:content) { 'Hello [NAME]!' }
+    
+    it 'stores and retrieves content' do
+      adapter.write(prompt_id, content)
+      expect(adapter.read(prompt_id)).to eq content
+    end
+  end
+end
+```
+
+## Documentation
+
+### Code Documentation
+
+Use YARD for inline documentation:
+
+```ruby
+# Renders a prompt with the given parameters
+#
+# @param parameters [Hash] Key-value pairs for parameter substitution
+# @return [String] The rendered prompt content
+# @raise [PromptNotFoundError] If the prompt cannot be found
+# @raise [MissingParametersError] If required parameters are missing
+#
+# @example Basic usage
+#   prompt = PromptManager::Prompt.new(id: 'welcome')
+#   result = prompt.render(name: 'John', company: 'Acme Corp')
+#
+# @example With nested parameters
+#   prompt.render(user: { name: 'Jane', email: 'jane@example.com' })
+def render(parameters = {})
+  # Implementation
+end
+```
+
+### README Updates
+
+Update the main README.md if your changes affect:
+- Installation instructions
+- Basic usage examples
+- Configuration options
+- Major features
+
+### Changelog
+
+Add entries to CHANGELOG.md for:
+- New features
+- Bug fixes
+- Breaking changes
+- Deprecations
+
+Format:
+```markdown
+## [Unreleased]
+
+### Added
+- New feature description
+
+### Changed
+- Changed behavior description
+
+### Fixed
+- Bug fix description
+
+### Deprecated
+- Deprecated feature description
+```
+
+## Submitting Changes
+
+### Before Submitting
+
+1. **Ensure all tests pass**: `bundle exec rspec`
+2. **Check code style**: `bundle exec rubocop`
+3. **Update documentation** as needed
+4. **Add changelog entry** if applicable
+5. **Rebase your branch** on the latest main branch
+
+### Pull Request Guidelines
+
+1. **Create a clear title**: "Add Redis storage adapter" or "Fix parameter parsing bug"
+
+2. **Write a detailed description**:
+   ```markdown
+   ## Summary
+   Brief description of what this PR does
+   
+   ## Changes
+   - Specific change 1
+   - Specific change 2
+   
+   ## Testing
+   - Added tests for new functionality
+   - All existing tests pass
+   
+   ## Documentation
+   - Updated relevant documentation files
+   ```
+
+3. **Link related issues**: "Closes #123" or "Fixes #456"
+
+4. **Request appropriate reviewers**
+
+### Pull Request Checklist
+
+- [ ] Tests added/updated and passing
+- [ ] Code follows style guidelines
+- [ ] Documentation updated
+- [ ] Changelog updated (if applicable)
+- [ ] No merge conflicts with main branch
+- [ ] PR description is clear and complete
+
+## Development Resources
+
+### Project Structure
+
+```
+prompt_manager/
+├── lib/
+│   └── prompt_manager/
+│       ├── prompt.rb              # Core Prompt class
+│       ├── storage/               # Storage adapters
+│       ├── directive_processor.rb # Directive processing
+│       └── configuration.rb      # Configuration management
+├── spec/                          # Test files
+│   ├── prompt_manager/
+│   ├── support/                   # Test helpers
+│   └── fixtures/                  # Test data
+├── docs/                          # Documentation
+└── examples/                      # Usage examples
+```
+
+### Key Classes and Modules
+
+- `PromptManager::Prompt` - Main interface for prompt operations
+- `PromptManager::Storage::Base` - Abstract storage adapter
+- `PromptManager::DirectiveProcessor` - Handles `//include` and custom directives
+- `PromptManager::Configuration` - Configuration management
+
+### Common Development Tasks
+
+```bash
+# Run tests for specific component
+bundle exec rspec spec/prompt_manager/storage/
+
+# Generate test coverage report
+COVERAGE=true bundle exec rspec
+
+# Check for security vulnerabilities
+bundle audit
+
+# Update dependencies
+bundle update
+
+# Generate documentation
+yard doc
+```
+
+## Getting Help
+
+- **GitHub Issues**: For bug reports and feature requests
+- **Discussions**: For questions and general discussion
+- **Email**: For security-related issues
+
+## Recognition
+
+Contributors are recognized in:
+- `CONTRIBUTORS.md` file
+- Release notes for major contributions
+- GitHub contributor statistics
+
+Thank you for contributing to PromptManager! 🎉

data/docs/development/roadmap.md

@@ -0,0 +1,234 @@
+# Roadmap
+
+This roadmap outlines the planned features, improvements, and long-term direction for PromptManager.
+
+## Current Version (0.5.x)
+
+### Completed ✅
+- Core prompt management functionality
+- FileSystem and ActiveRecord storage adapters
+- Parameter substitution with nested object support
+- ERB template integration
+- Basic directive processing (`//include`)
+- Environment variable substitution
+- Parameter history tracking
+- Comprehensive error handling
+- Documentation website
+
+### In Progress 🚧
+- Performance optimization for large prompt libraries
+- Enhanced search and filtering capabilities
+- Improved error messages and debugging tools
+
+## Version 1.0.0 - Stable Foundation (Q2 2024)
+
+### Major Features
+- **Stable API**: Finalized public API with semantic versioning commitment
+- **Enhanced Storage Options**: 
+  - Redis adapter
+  - S3/cloud storage adapter
+  - Encrypted storage support
+- **Advanced Templating**:
+  - Custom directive system
+  - Template inheritance
+  - Conditional rendering improvements
+- **Developer Experience**:
+  - CLI tool for prompt management
+  - VS Code extension for syntax highlighting
+  - Interactive prompt editor
+
+### Performance & Scalability
+- Lazy loading for large prompt libraries
+- Caching layer improvements
+- Bulk operations API
+- Memory usage optimization
+
+### Quality Assurance
+- 95%+ test coverage
+- Performance benchmarking
+- Security audit
+- Documentation completeness review
+
+## Version 1.1.0 - Collaboration Features (Q3 2024)
+
+### Team Collaboration
+- **Version Control Integration**:
+  - Git-based prompt versioning
+  - Diff and merge capabilities for prompts
+  - Branch-based development workflows
+- **Multi-user Support**:
+  - User permissions and access control
+  - Approval workflows for prompt changes
+  - Audit logging for all operations
+
+### Content Management
+- **Prompt Organization**:
+  - Tags and categories
+  - Collections and workspaces
+  - Advanced search with faceted navigation
+- **Quality Control**:
+  - Prompt linting and validation
+  - A/B testing framework
+  - Usage analytics and insights
+
+## Version 1.2.0 - AI Integration (Q4 2024)
+
+### AI-Powered Features
+- **Intelligent Prompt Assistance**:
+  - AI-powered prompt generation
+  - Optimization suggestions
+  - Automatic parameter extraction
+- **Smart Search**:
+  - Semantic search using embeddings
+  - Similar prompt recommendations
+  - Context-aware suggestions
+
+### Integration Capabilities
+- **LLM Provider Integration**:
+  - Direct integration with OpenAI, Anthropic, etc.
+  - Prompt testing and validation
+  - Response caching and optimization
+- **Workflow Automation**:
+  - Automated prompt testing
+  - Performance monitoring
+  - Quality metrics tracking
+
+## Version 2.0.0 - Enterprise Platform (Q2 2025)
+
+### Enterprise Features
+- **Scalability**:
+  - Multi-tenant architecture
+  - Horizontal scaling support
+  - Enterprise-grade security
+- **Integration Platform**:
+  - REST API and GraphQL endpoints
+  - Webhook system
+  - Third-party integrations (Slack, Teams, etc.)
+
+### Advanced Analytics
+- **Usage Intelligence**:
+  - Prompt performance analytics
+  - User behavior insights
+  - ROI tracking and reporting
+- **Optimization Engine**:
+  - Automatic prompt optimization
+  - Performance regression detection
+  - Resource usage optimization
+
+### Governance & Compliance
+- **Security & Compliance**:
+  - SOC 2 Type II compliance
+  - GDPR/CCPA compliance tools
+  - Data encryption at rest and in transit
+- **Governance**:
+  - Policy management
+  - Compliance reporting
+  - Data retention controls
+
+## Long-term Vision (2025+)
+
+### Platform Evolution
+- **Microservices Architecture**: Break down into specialized services
+- **Event-Driven Architecture**: Real-time prompt updates and notifications  
+- **Global CDN**: Distributed prompt delivery for low latency
+- **Multi-Language Support**: Native support for multiple programming languages
+
+### AI/ML Advancements
+- **Prompt Evolution**: AI that learns and improves prompts over time
+- **Contextual Intelligence**: Automatic context injection based on usage patterns
+- **Predictive Analytics**: Forecast prompt performance and usage trends
+
+### Developer Ecosystem
+- **Plugin System**: Extensible architecture for third-party plugins
+- **Marketplace**: Community-driven prompt and template sharing
+- **SDK Library**: Native SDKs for popular languages and frameworks
+
+## Feature Requests & Community Input
+
+### Highly Requested Features
+1. **Visual Prompt Editor** - GUI for non-technical users
+2. **Prompt Templates Gallery** - Pre-built templates for common use cases
+3. **Integration Connectors** - Native connectors for popular tools
+4. **Mobile App** - Mobile application for prompt management
+5. **Backup/Export Tools** - Data portability and backup solutions
+
+### Research & Exploration
+- **Prompt Compression**: Techniques to reduce prompt size while maintaining effectiveness
+- **Multi-Modal Prompts**: Support for image, audio, and video prompts
+- **Federated Learning**: Collaborative improvement without sharing sensitive data
+- **Quantum-Safe Encryption**: Future-proof security measures
+
+## Release Schedule
+
+### Release Cadence
+- **Major Releases**: Every 6-9 months
+- **Minor Releases**: Every 2-3 months  
+- **Patch Releases**: As needed (security, critical bugs)
+- **Beta/RC Releases**: 2-4 weeks before major releases
+
+### Version Support Policy
+- **Latest Major Version**: Full support (features, bugs, security)
+- **Previous Major Version**: Bug fixes and security updates for 18 months
+- **Legacy Versions**: Security updates only for 12 months after end of life
+
+## Contributing to the Roadmap
+
+### How to Influence the Roadmap
+1. **Feature Requests**: Submit detailed feature requests via GitHub Issues
+2. **Community Discussion**: Participate in roadmap discussions
+3. **User Research**: Provide feedback through surveys and interviews
+4. **Pull Requests**: Contribute implementations for planned features
+
+### Prioritization Criteria
+- **User Impact**: How many users benefit and to what degree
+- **Strategic Alignment**: Fits with long-term vision and goals
+- **Technical Feasibility**: Implementation complexity and maintainability
+- **Community Support**: Level of community interest and contribution
+- **Business Value**: Commercial viability and sustainability
+
+### Feedback Channels
+- **GitHub Discussions**: For feature ideas and architectural discussions
+- **User Surveys**: Quarterly surveys on feature priorities
+- **Community Calls**: Monthly calls with active contributors
+- **Beta Programs**: Early access to new features for feedback
+
+## Migration & Compatibility
+
+### Breaking Changes Policy
+- **Semantic Versioning**: Follow strict semantic versioning
+- **Deprecation Warnings**: 6-month warning period before removal
+- **Migration Guides**: Detailed guides for all breaking changes
+- **Automated Migration**: Tools to assist with major version upgrades
+
+### Backward Compatibility
+- **API Stability**: Public API remains stable within major versions
+- **Configuration**: Configuration format maintained across minor versions
+- **Storage Format**: Storage adapters maintain backward compatibility
+- **Plugin Interface**: Plugin API versioning and compatibility matrix
+
+## Success Metrics
+
+### Technical Metrics
+- **Performance**: Sub-100ms prompt rendering for 95th percentile
+- **Reliability**: 99.9% uptime for cloud-hosted services
+- **Scalability**: Support for 1M+ prompts per instance
+- **Security**: Zero critical security vulnerabilities
+
+### Adoption Metrics  
+- **Community Growth**: 10,000+ GitHub stars by end of 2024
+- **Enterprise Adoption**: 100+ enterprise customers by 2025
+- **Ecosystem**: 50+ community-contributed plugins and integrations
+- **Documentation**: 95%+ documentation coverage for all features
+
+### Quality Metrics
+- **Code Coverage**: Maintain 90%+ test coverage
+- **Documentation Score**: 4.5/5 average user rating
+- **Support Response**: <24 hour response time for critical issues
+- **Community Satisfaction**: 8/10 average satisfaction score
+
+---
+
+*This roadmap is a living document that evolves based on user feedback, market conditions, and technical discoveries. While we strive to deliver on these plans, priorities may shift to better serve our community.*
+
+**Last Updated**: January 2024  
+**Next Review**: April 2024