opaque_id 1.3.0 → 1.6.0

data/tasks/0002-prd-publishing-release-automation.md

@@ -1,206 +0,0 @@
-# Product Requirements Document: Publishing & Release Automation
-
-## Introduction/Overview
-
-This PRD outlines the implementation of a fully automated publishing and release system for the OpaqueId Ruby gem. The system will automatically version, test, and publish releases to RubyGems.org based on conventional commits, eliminating manual release processes and ensuring consistent, professional releases.
-
-**Problem**: Manual release processes are error-prone, time-consuming, and inconsistent. Without automated versioning and publishing, releases can be delayed, version numbers can be inconsistent, and changelogs can be incomplete.
-
-**Goal**: Implement a fully automated CI/CD pipeline that handles versioning, testing, changelog generation, and publishing based on conventional commits and the state of the main branch.
-
-## Goals
-
-1. **Automated Versioning**: Automatically determine version bumps (patch/minor/major) based on conventional commit types
-2. **Automated Publishing**: Automatically publish to RubyGems.org when changes are ready
-3. **Quality Gates**: Ensure all tests pass, code quality standards are met, and security checks pass before release
-4. **Automated Changelog**: Generate changelog entries from conventional commits
-5. **Dependency Management**: Automatically check for and update dependencies weekly
-6. **Commit Standardization**: Enforce conventional commit format for consistent messaging
-7. **Security**: Use RubyGems trusted publishing for secure, keyless releases
-
-## User Stories
-
-### As a Developer
-
-- **US1**: I want my commits to automatically trigger appropriate version bumps so that I don't have to manually manage version numbers
-- **US2**: I want releases to be published automatically when I push to main so that I don't have to remember to manually publish
-- **US3**: I want commit message validation so that I follow consistent formatting standards
-- **US4**: I want automated dependency updates so that my gem stays secure and up-to-date
-
-### As a Maintainer
-
-- **US5**: I want automated testing and quality checks before release so that I can trust the published code
-- **US6**: I want automated changelog generation so that users know what changed in each release
-- **US7**: I want security scanning before release so that vulnerabilities are caught early
-
-### As a User
-
-- **US8**: I want consistent, predictable releases so that I can trust the gem's stability
-- **US9**: I want clear changelogs so that I understand what changed between versions
-
-## Functional Requirements
-
-### 1. Conventional Commits Integration
-
-1.1. **Commit Message Validation**: Enforce conventional commit format (feat:, fix:, docs:, etc.) on all commits
-1.2. **Commit Linting**: Use commitlint or similar tool to validate commit message format
-1.3. **Pre-commit Hooks**: Automatically validate commit messages before they are accepted
-1.4. **Commit Types**: Support standard types: feat, fix, docs, style, refactor, perf, test, chore, ci, build
-
-### 2. Automated Versioning
-
-2.1. **Semantic Versioning**: Use semantic versioning (MAJOR.MINOR.PATCH) based on conventional commits
-2.2. **Version Bump Logic**:
-
-- `feat:` commits → MINOR version bump
-- `fix:` commits → PATCH version bump
-- `BREAKING CHANGE:` or `!` → MAJOR version bump
-- Other types → no version bump
-  2.3. **Version Detection**: Automatically detect when version should be bumped based on unreleased commits
-  2.4. **Version File Update**: Automatically update `lib/opaque_id/version.rb` with new version
-
-### 3. GitHub Actions Workflow
-
-3.1. **Single Workflow**: Update existing `main.yml` to include release automation
-3.2. **Trigger Conditions**: Run on push to main branch when unreleased changes exist
-3.3. **Workflow Steps**:
-
-- Checkout code
-- Setup Ruby environment
-- Install dependencies
-- Run tests
-- Run RuboCop
-- Security audit
-- Determine version bump
-- Update version file
-- Generate changelog
-- Create git tag
-- Publish to RubyGems.org
-- Create GitHub release
-
-### 4. Quality Gates
-
-4.1. **Test Execution**: Run full test suite before any release
-4.2. **Code Quality**: Run RuboCop and fail if violations exist
-4.3. **Security Scanning**: Run `bundle audit` to check for vulnerable dependencies
-4.4. **Dependency Check**: Ensure all dependencies are up-to-date and secure
-
-### 5. Changelog Generation
-
-5.1. **Automated Generation**: Generate changelog from conventional commits since last release
-5.2. **Changelog Format**: Use conventional changelog format with categorized sections
-5.3. **Changelog Sections**: Features, Bug Fixes, Breaking Changes, Documentation, etc.
-5.4. **Changelog Update**: Automatically update `CHANGELOG.md` with new entries
-
-### 6. RubyGems Publishing
-
-6.1. **Trusted Publishing**: Use RubyGems trusted publishing (no API keys required)
-6.2. **MFA Enforcement**: Ensure MFA is required for publishing (already configured)
-6.3. **Build Process**: Build gem package before publishing
-6.4. **Publish Process**: Automatically push to RubyGems.org when all checks pass
-
-### 7. Dependabot Integration
-
-7.1. **Weekly Updates**: Check for dependency updates every Monday at 9 AM
-7.2. **Update Types**: Check for both direct and indirect dependency updates
-7.3. **Security Updates**: Prioritize security-related updates
-7.4. **Update Strategy**: Create pull requests for dependency updates
-
-### 8. Git Tag Management
-
-8.1. **Automatic Tagging**: Create git tags for each release (e.g., `v1.2.3`)
-8.2. **Tag Format**: Use semantic versioning format with `v` prefix
-8.3. **Tag Push**: Automatically push tags to GitHub repository
-8.4. **GitHub Release**: Create GitHub release with changelog and tag
-
-## Non-Goals (Out of Scope)
-
-1. **Manual Release Override**: No manual release triggers or overrides
-2. **Multiple Branch Support**: Only support releases from main branch
-3. **Pre-release Versions**: No support for alpha/beta/rc versions initially
-4. **Monorepo Support**: Single gem repository only
-5. **Custom Versioning Logic**: No custom versioning rules beyond conventional commits
-6. **Rollback Automation**: No automatic rollback of failed releases
-
-## Technical Considerations
-
-### Dependencies
-
-- **Release Please**: Google's tool for PR-based versioning and changelog generation
-- **Bundler's release tasks**: Built-in rake tasks for building and tagging (already present)
-- **commitlint**: For commit message validation (optional)
-- **bundle-audit**: For security scanning
-
-### GitHub Actions
-
-- **googleapis/release-please-action**: For creating release PRs and versioning
-- **rubygems/release-gem**: For RubyGems publishing with trusted publishing
-- **actions/checkout**: For code checkout
-- **ruby/setup-ruby**: For Ruby environment setup
-
-### Configuration Files
-
-- **release-please-config.json**: Release Please configuration
-- **dependabot.yml**: Dependency update configuration
-- **.github/workflows/release-please.yml**: Release PR workflow
-- **.github/workflows/publish.yml**: Publishing workflow
-
-### RubyGems Trusted Publishing
-
-- Configure trusted publishing on RubyGems.org
-- Use GitHub OIDC for authentication
-- No API keys or secrets required
-
-## Success Metrics
-
-1. **Release Automation**: 100% of releases are automated (no manual intervention)
-2. **Release Frequency**: Ability to release multiple times per day if needed
-3. **Quality Gates**: 0% of releases with failing tests or security issues
-4. **Commit Compliance**: 100% of commits follow conventional commit format
-5. **Dependency Currency**: Dependencies updated within 7 days of availability
-6. **Release Time**: From commit to published gem in under 10 minutes
-
-## Open Questions
-
-1. **Commit Message Enforcement**: Should we use pre-commit hooks or GitHub Actions validation?
-2. **Changelog Format**: Should we use conventional-changelog or custom format?
-3. **Version Bump Strategy**: Should we batch multiple commits into single releases?
-4. **Rollback Strategy**: How should we handle failed releases or rollbacks?
-5. **Notification Strategy**: Should we notify maintainers of successful/failed releases?
-6. **Branch Protection**: Should we require status checks before merging to main?
-
-## Implementation Priority
-
-### Phase 1: Core Automation
-
-- Conventional commits validation
-- Automated versioning
-- Basic GitHub Actions workflow
-- RubyGems publishing
-
-### Phase 2: Quality & Security
-
-- Quality gates (tests, RuboCop, security)
-- Automated changelog generation
-- Dependabot integration
-
-### Phase 3: Polish & Monitoring
-
-- Enhanced notifications
-- Release monitoring
-- Performance optimization
-
-## Acceptance Criteria
-
-- [ ] All commits follow conventional commit format
-- [ ] Version numbers are automatically bumped based on commit types
-- [ ] Releases are automatically published to RubyGems.org
-- [ ] Changelog is automatically generated from commits
-- [ ] All tests pass before release
-- [ ] RuboCop passes before release
-- [ ] Security audit passes before release
-- [ ] Dependencies are automatically updated weekly
-- [ ] Git tags are automatically created for releases
-- [ ] GitHub releases are automatically created
-- [ ] RubyGems trusted publishing is configured
-- [ ] No manual intervention required for releases

data/tasks/0003-prd-documentation-site.md

@@ -1,191 +0,0 @@
-# Product Requirements Document: OpaqueId Documentation Site
-
-## Introduction/Overview
-
-Create a professional documentation website for the OpaqueId Ruby gem using [Just the Docs](https://just-the-docs.com) Jekyll theme. The site will provide comprehensive, developer-focused documentation that mirrors the README content but with improved navigation, search capabilities, and a clean, minimal design similar to the Just the Docs site itself.
-
-**Problem Solved:** The current README is comprehensive but long (1600+ lines), making it difficult to navigate and find specific information quickly. A dedicated documentation site will improve developer experience and make the gem more accessible.
-
-**Goal:** Create a professional, searchable documentation site that makes OpaqueId easy to understand and implement for developers.
-
-## Goals
-
-1. **Improve Developer Experience**: Provide easy navigation and search for finding specific documentation
-2. **Professional Presentation**: Create a polished, modern documentation site that reflects the quality of the gem
-3. **Maintain Content Quality**: Preserve all valuable information from the README while improving organization
-4. **Enable Auto-Deployment**: Set up GitHub Actions for automatic deployment on successful pushes
-5. **Ensure Accessibility**: Make documentation accessible and mobile-friendly
-6. **Minimize Maintenance**: Keep the site simple and maintainable
-
-## User Stories
-
-- **As a developer** evaluating OpaqueId, I want to quickly understand what the gem does and how to install it
-- **As a developer** implementing OpaqueId, I want to find specific configuration options and usage examples
-- **As a developer** troubleshooting issues, I want to search for specific error messages or solutions
-- **As a developer** learning advanced features, I want to explore performance benchmarks and security considerations
-- **As a developer** contributing to the project, I want to understand the development setup and guidelines
-
-## Functional Requirements
-
-### 1. Site Structure & Navigation
-
-1.1. Create a `/docs` directory with Jekyll site structure
-1.2. Implement sidebar navigation based on README Table of Contents
-1.3. Use minimal, flat navigation structure (no collapsible sections)
-1.4. Include search functionality using Just the Docs built-in search
-1.5. Add "Getting Started" quick start guide as a separate page
-
-### 2. Content Organization
-
-2.1. Convert README sections into individual documentation pages
-2.2. Create logical page hierarchy: Home → Getting Started → Installation → Usage → Configuration → etc.
-2.3. Maintain all existing content from README
-2.4. Add code syntax highlighting for Ruby examples
-2.5. Include proper cross-references between pages
-
-### 3. Design & Styling
-
-3.1. Use Just the Docs theme with default light/dark mode switching
-3.2. Apply minimal design similar to just-the-docs.com
-3.3. Include OpaqueId branding and gem badges
-3.4. Ensure responsive design for mobile devices
-3.5. Use consistent typography and spacing
-
-### 4. GitHub Pages Integration
-
-4.1. Configure site for `https://nyaggah.github.io/opaque_id`
-4.2. Set up GitHub Actions workflow for automatic deployment
-4.3. Deploy on successful pushes to main branch
-4.4. Include proper Jekyll configuration for GitHub Pages
-
-### 5. Content Pages
-
-5.1. **Home**: Overview, badges, quick introduction
-5.2. **Getting Started**: Step-by-step installation and basic usage
-5.3. **Installation**: Detailed installation instructions and requirements
-5.4. **Usage**: Standalone and ActiveRecord integration examples
-5.5. **Configuration**: All configuration options and examples
-5.6. **Alphabets**: Built-in alphabets and custom alphabet guide
-5.7. **Algorithms**: Technical details about fast path and unbiased algorithms
-5.8. **Performance**: Benchmarks and optimization tips
-5.9. **Security**: Security considerations and best practices
-5.10. **Use Cases**: Real-world examples and applications
-5.11. **Development**: Contributing guidelines and development setup
-5.12. **API Reference**: Complete method documentation
-
-### 6. Technical Implementation
-
-6.1. Use Jekyll with Just the Docs theme
-6.2. Configure `_config.yml` for GitHub Pages
-6.3. Set up proper front matter for all pages
-6.4. Include necessary Jekyll plugins for GitHub Pages
-6.5. Optimize for fast loading and SEO
-
-## Non-Goals (Out of Scope)
-
-- **Live Code Examples**: No interactive demos or live code execution
-- **Version-Specific Documentation**: Single version documentation only
-- **Automatic README Sync**: Manual content maintenance
-- **Custom Domain**: Using default GitHub.io domain
-- **Breadcrumb Navigation**: Sidebar navigation only
-- **User Authentication**: Public documentation only
-- **Comments/Feedback System**: Static documentation only
-
-## Design Considerations
-
-### Visual Design
-
-- **Theme**: [Just the Docs](https://just-the-docs.com) Jekyll theme
-- **Color Scheme**: Default light/dark mode switching
-- **Layout**: Clean, minimal design with focus on content
-- **Typography**: Clear, readable fonts with proper hierarchy
-- **Navigation**: Left sidebar with flat structure
-
-### Content Structure
-
-- **Homepage**: Hero section with badges, overview, and quick start
-- **Sidebar**: Logical grouping of documentation sections
-- **Search**: Full-text search across all documentation
-- **Code Examples**: Syntax-highlighted Ruby code blocks
-- **Cross-References**: Links between related sections
-
-## Technical Considerations
-
-### Jekyll Configuration
-
-- Use gem-based approach with `just-the-docs` gem
-- Configure for GitHub Pages compatibility
-- Include necessary plugins: jekyll-feed, jekyll-sitemap, jekyll-seo-tag
-- Set up proper permalinks and URL structure
-
-### GitHub Actions Workflow
-
-- Trigger on pushes to main branch
-- Build Jekyll site
-- Deploy to GitHub Pages
-- Include proper error handling and notifications
-
-### File Structure
-
-```
-/docs/
-├── _config.yml
-├── Gemfile
-├── index.md (Home)
-├── getting-started.md
-├── installation.md
-├── usage.md
-├── configuration.md
-├── alphabets.md
-├── algorithms.md
-├── performance.md
-├── security.md
-├── use-cases.md
-├── development.md
-├── api-reference.md
-└── assets/
-    └── images/
-```
-
-## Success Metrics
-
-1. **Developer Adoption**: Increased gem downloads and usage
-2. **User Engagement**: Time spent on documentation pages
-3. **Search Usage**: Frequency of search functionality usage
-4. **Page Performance**: Fast loading times (< 3 seconds)
-5. **Mobile Usage**: Successful mobile documentation access
-6. **SEO Performance**: High search engine rankings for OpaqueId-related queries
-
-## Open Questions
-
-1. Should we include a changelog page or link to GitHub releases?
-2. Do we want to include a "Troubleshooting" section for common issues?
-3. Should we add a "Migration Guide" for users switching from nanoid.rb?
-4. Do we want to include performance comparison charts or keep them as tables?
-5. Should we add a "Community" section with links to discussions and support?
-
-## Implementation Priority
-
-### Phase 1: Core Setup
-
-- Set up Jekyll site structure
-- Configure GitHub Pages deployment
-- Create basic page structure
-
-### Phase 2: Content Migration
-
-- Convert README content to individual pages
-- Set up navigation and cross-references
-- Add code syntax highlighting
-
-### Phase 3: Enhancement
-
-- Add search functionality
-- Optimize performance and SEO
-- Polish design and user experience
-
-### Phase 4: Launch
-
-- Deploy to GitHub Pages
-- Test all functionality
-- Announce to community