conversant 1.0.16

data/RELEASE.md

@@ -0,0 +1,726 @@
+# Conversant Gem - Developer Guide
+
+A complete guide for developing, publishing, and maintaining the Conversant Ruby gem.
+
+## Table of Contents
+
+1. [Quick Start](#quick-start)
+2. [Architecture](#architecture)
+3. [Publishing the Gem](#publishing-the-gem)
+4. [Version Management](#version-management)
+5. [Documentation](#documentation)
+6. [GitLab CI/CD](#gitlab-cicd)
+7. [Troubleshooting](#troubleshooting)
+8. [Common Issues & Solutions](#common-issues--solutions)
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Ruby 2.7+ installed
+- RubyGems account (https://rubygems.org)
+- GitLab repository access
+- Redis server (for testing)
+
+### Initial Setup
+
+```bash
+# Clone the repository
+git clone https://gitlab.vnetwork.dev/gems/conversant.git
+cd conversant
+
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Generate documentation
+bundle exec yard doc
+```
+
+---
+
+## Architecture
+
+### Directory Structure
+
+```
+lib/conversant/
+├── v3/
+│   ├── base.rb                    # Base class for all services
+│   ├── http_client.rb             # HTTP client module
+│   ├── mixins/
+│   │   └── authentication.rb      # Authentication mixin
+│   └── services/
+│       ├── cdn.rb                  # Main CDN service class
+│       ├── cdn/                    # CDN nested services
+│       │   ├── domain.rb           # Domain management
+│       │   ├── business.rb         # Business metrics
+│       │   └── certificate.rb      # Certificate management
+│       ├── lms.rb                  # Main LMS service class
+│       ├── lms/                    # LMS nested services
+│       │   ├── domain.rb           # LMS domain management
+│       │   └── dashboard.rb        # Dashboard metrics
+│       ├── portal.rb               # Portal service
+│       └── vms.rb                  # VMS service
+```
+
+### Important: Loading Order
+
+**Critical for Rails/Zeitwerk compatibility:**
+
+1. Main service files (e.g., `cdn.rb`) define the parent class
+2. Nested service files are loaded AFTER the parent class definition
+3. This is achieved by placing `require_relative` statements at the END of the parent class file
+
+```ruby
+# lib/conversant/v3/services/cdn.rb
+module Conversant
+  module V3
+    module Services
+      class CDN < ::Conversant::V3::Base
+        # ... class implementation ...
+      end
+    end
+  end
+end
+
+# IMPORTANT: Load nested classes AFTER CDN is defined
+require_relative 'cdn/domain'
+require_relative 'cdn/business'
+require_relative 'cdn/certificate'
+```
+
+### Class Hierarchy
+
+```
+Conversant::V3::Base
+├── Conversant::V3::Services::Portal
+├── Conversant::V3::Services::CDN
+│   ├── CDN::Analytics
+│   ├── CDN::Monitoring
+│   ├── CDN::Audit
+│   ├── CDN::Domain
+│   ├── CDN::Business
+│   └── CDN::Certificate
+├── Conversant::V3::Services::LMS
+│   ├── LMS::Job
+│   ├── LMS::Domain
+│   └── LMS::Dashboard
+└── Conversant::V3::Services::VMS
+    ├── VMS::VodTranscoding
+    ├── VMS::Analytics
+    └── VMS::Business
+```
+
+### Type Signatures (RBS)
+
+Type signatures are located in `sig/` directory:
+
+```
+sig/conversant/
+├── v3.rbs                          # V3 module types
+├── v3/
+│   └── services/
+│       ├── cdn.rbs                 # CDN service types
+│       ├── cdn/
+│       │   ├── analytics.rbs
+│       │   ├── domain.rbs
+│       │   └── ...
+│       ├── lms.rbs                 # LMS service types
+│       ├── portal.rbs              # Portal service types
+│       └── vms.rbs                 # VMS service types
+```
+
+---
+
+## Publishing the Gem
+
+### First-Time Setup
+
+```bash
+# Login to RubyGems (one-time)
+gem signin
+# Enter your RubyGems.org credentials
+```
+
+### Quick Publish Commands
+
+```bash
+# Option 1: Automated script (recommended)
+./publish.sh
+
+# Option 2: Manual commands
+gem build conversant.gemspec
+gem push conversant-1.0.0.gem
+```
+
+### Step-by-Step Manual Publishing
+
+#### 1. Prepare the Gem
+
+```bash
+# Clean previous builds
+rm -f *.gem
+
+# Run tests
+bundle exec rspec
+
+# Build the gem
+gem build conversant.gemspec
+```
+
+#### 2. Verify the Build
+
+```bash
+# Check gem contents
+gem specification conversant-1.0.0.gem
+
+# Test local installation
+gem install ./conversant-1.0.0.gem
+```
+
+#### 3. Publish to RubyGems
+
+```bash
+# Push to RubyGems.org
+gem push conversant-1.0.0.gem
+```
+
+#### 4. Push to GitLab
+
+```bash
+# Initialize git (if needed)
+git init
+git remote add origin https://gitlab.vnetwork.dev/gems/conversant.git
+
+# Commit and push
+git add .
+git commit -m "Release version 1.0.0"
+git push -u origin main
+
+# Create and push tag
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```
+
+### Publishing Checklist
+
+- [ ] Tests passing (`bundle exec rspec`)
+- [ ] Version updated in `lib/conversant/version.rb`
+- [ ] CHANGELOG.md updated
+- [ ] Documentation generated (`bundle exec yard doc`)
+- [ ] Gem builds without warnings
+- [ ] README.md is current
+- [ ] Commit all changes
+- [ ] Tag the release
+- [ ] Push to RubyGems (`gem push conversant-X.Y.Z.gem`)
+- [ ] Wait 1-2 hours for RubyDoc.info to process automatically
+- [ ] Visit https://rubydoc.info/gems/conversant to check/trigger docs
+
+---
+
+## Version Management
+
+### Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+
+1.0.0 -> 1.0.1  # Patch: Bug fixes
+1.0.0 -> 1.1.0  # Minor: New features (backward compatible)
+1.0.0 -> 2.0.0  # Major: Breaking changes
+```
+
+### Releasing a New Version
+
+#### 1. Update Version
+
+```ruby
+# lib/conversant/version.rb
+module Conversant
+  VERSION = "1.0.1"
+end
+```
+
+#### 2. Update CHANGELOG
+
+```markdown
+## [1.0.1] - 2025-01-02
+### Fixed
+- Bug fixes from version 1.0.0
+### Added
+- New feature description
+```
+
+#### 3. Build and Publish
+
+```bash
+# Commit changes
+git add -A
+git commit -m "Bump version to 1.0.1"
+
+# Build and publish
+gem build conversant.gemspec
+gem push conversant-1.0.1.gem
+
+# Tag release
+git tag -a v1.0.1 -m "Release version 1.0.1"
+git push origin main --tags
+```
+
+### Managing Published Versions
+
+#### Yank a Version (Recommended)
+
+```bash
+# Remove version from RubyGems (keeps for existing users)
+gem yank conversant -v 1.0.0
+
+# Undo yank if needed
+gem yank conversant -v 1.0.0 --undo
+```
+
+#### Check Published Versions
+
+```bash
+# List remote versions
+gem list conversant --remote --all
+
+# Check if gem exists
+gem search ^conversant$ --remote
+```
+
+#### Important Notes
+
+- **Yanked versions cannot be republished** with the same number
+- **Always bump version** after yanking
+- **Prefer yanking over deletion** to avoid breaking existing apps
+
+---
+
+## Documentation
+
+### Generating Documentation
+
+#### Local Generation
+
+```bash
+# Generate HTML documentation
+bundle exec yard doc
+
+# With statistics
+bundle exec yard doc --stats
+
+# Serve documentation locally
+bundle exec yard server
+# Visit http://localhost:8808
+```
+
+#### Check Coverage
+
+```bash
+bundle exec yard stats
+
+# Example output:
+# Files:          10
+# Modules:         7 (    5 undocumented)
+# Classes:        12 (    9 undocumented)
+# Methods:        45 (   27 undocumented)
+#  48.31% documented
+```
+
+### Publishing to RubyDoc.info
+
+#### Automatic Processing
+
+RubyDoc.info automatically generates documentation for published gems:
+
+1. **Wait 10-30 minutes** after publishing
+2. Visit: https://rubydoc.info/gems/conversant/1.0.10
+3. Documentation should appear automatically
+
+#### Manual Trigger
+
+If documentation doesn't appear:
+
+1. **Visit**: https://rubydoc.info/gems/conversant/1.0.10/index
+2. Click **"Build Docs"** button if available
+3. Or visit: https://rubydoc.info/gems/conversant/frames
+
+#### Triggering RubyDoc.info Documentation Generation
+
+If documentation is not generating after 30+ minutes:
+
+**Method 1: Webhook API (Recommended)**
+Trigger documentation build via POST request (returns HTTP 202 on success):
+```bash
+# Use the appropriate RubyDoc.info webhook endpoint
+# Note: Replace with the correct endpoint your team discovered
+curl https://rubydoc.info/gems/conversant/1.0.10/index
+```
+
+**Method 2: Direct URL Access**
+Simply visit the gem's documentation URL in your browser:
+```
+https://rubydoc.info/gems/conversant/1.0.10
+```
+This often triggers the documentation generation process.
+
+**Method 3: Yank and Republish (Last Resort)**
+If docs still don't appear after several hours:
+```bash
+# 1. Yank the current version
+gem yank conversant -v 1.0.6
+
+# 2. Bump the patch version
+# Edit lib/conversant/version.rb: VERSION = "1.0.7"
+
+# 3. Rebuild and republish
+gem build conversant.gemspec
+gem push conversant-1.0.7.gem
+
+# 4. Wait 10-30 minutes and visit https://rubydoc.info/gems/conversant
+```
+
+#### Troubleshooting Missing Documentation
+
+If you see "We haven't generated any docs for conversant" on RubyDoc.info:
+
+**Step-by-step solution:**
+
+1. **Verify gem is published:**
+   ```bash
+   # Check gem exists on RubyGems
+   gem list conversant --remote --all
+
+   # View gem metadata (should show your gem info)
+   curl https://rubygems.org/api/v1/gems/conversant.json
+   ```
+
+2. **Wait patiently**: First-time gems can take **1-2 hours** to process
+
+3. **Visit directly**: Access https://rubydoc.info/gems/conversant in your browser
+
+4. **Check YARD compatibility locally:**
+   ```bash
+   bundle exec yard doc --debug
+   # Should complete without errors
+   ```
+
+5. **Verify gemspec metadata**: Confirm `documentation_uri` is set (already configured in conversant.gemspec)
+
+6. **Try alternative version URL**: https://rubydoc.info/gems/conversant/1.0.6/frames
+
+**Common causes:**
+- Gem was just published (patience required - can take up to 2 hours)
+- RubyDoc.info processing queue is busy (retry next day)
+- YARD parsing errors in code comments (check with `yard doc --debug`)
+- Gem name conflicts or special characters
+
+**Important Notes:**
+- RubyDoc.info processes gems automatically from RubyGems.org
+- There is no official webhook/API to force processing
+- If docs don't appear after 24 hours, consider reporting to RubyDoc.info
+- Alternative: Host docs yourself with `yard doc` and GitHub Pages
+
+### Documentation URLs
+
+Once processed, documentation is available at:
+
+- **Latest**: https://rubydoc.info/gems/conversant
+- **Specific Version**: https://rubydoc.info/gems/conversant/1.0.0
+- **README**: https://rubydoc.info/gems/conversant/file/README.md
+- **API Docs**: https://rubydoc.info/gems/conversant/Conversant
+
+### Writing YARD Documentation
+
+#### Basic Method Documentation
+
+```ruby
+# Description of the method
+#
+# @param customer_id [String, Integer] customer identifier
+# @param options [Hash] additional options
+#
+# @return [Hash] response data
+# @raise [AuthenticationError] if auth fails
+#
+# @example
+#   portal = Conversant::V3.portal('12345')
+#   data = portal.appliances
+#
+# @since 1.0.0
+def appliances(gte = nil, lte = nil)
+  # implementation
+end
+```
+
+#### Best Practices
+
+1. Document all public methods
+2. Include parameter types and descriptions
+3. Add usage examples
+4. Specify return types
+5. List possible exceptions
+
+---
+
+## GitLab CI/CD
+
+### Pipeline Configuration
+
+The `.gitlab-ci.yml` file configures automated testing and publishing:
+
+```yaml
+stages:
+  - test
+  - build
+  - publish
+
+# Test on multiple Ruby versions
+test:ruby-3.0:
+  stage: test
+  image: ruby:3.0
+  script:
+    - bundle install
+    - bundle exec rspec
+
+# Build gem
+build:
+  stage: build
+  script:
+    - gem build conversant.gemspec
+  artifacts:
+    paths:
+      - "*.gem"
+
+# Publish to RubyGems (manual)
+publish:rubygems:
+  stage: publish
+  script:
+    - gem push *.gem
+  when: manual
+  only:
+    - tags
+```
+
+### Setting Up CI/CD Variables
+
+1. Go to: https://gitlab.vnetwork.dev/gems/conversant/-/settings/ci_cd
+2. Add Variable: `RUBYGEMS_API_KEY` = your RubyGems API key
+3. Mark as "Protected" and "Masked"
+
+### Triggering Automated Publishing
+
+```bash
+# Create tag to trigger pipeline
+git tag -a v1.0.1 -m "Release version 1.0.1"
+git push origin v1.0.1
+
+# Go to GitLab pipelines and manually trigger publish job
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Gem Build Failures
+
+```bash
+# Validate gemspec
+ruby -c conversant.gemspec
+gem build conversant.gemspec --strict
+
+# Check for missing files
+git ls-files -z
+```
+
+#### Authentication Issues
+
+```bash
+# Reset RubyGems credentials
+rm ~/.gem/credentials
+gem signin
+
+# Check ownership
+gem owner conversant
+```
+
+#### Documentation Not Showing on RubyDoc.info
+
+**Issue**: "We haven't generated any docs for conversant" message
+
+**Solutions** (in order):
+
+1. **Check gem is published:**
+   ```bash
+   gem list conversant --remote --all
+   curl https://rubygems.org/api/v1/gems/conversant.json
+   
+   curl -X POST "https://www.rubydoc.info/gems/conversant/1.0.6"
+   ```
+
+2. **Wait 1-2 hours** for RubyDoc.info automatic processing (first-time gems take longer)
+
+3. **Visit directly** to trigger/check processing:
+   - https://rubydoc.info/gems/conversant
+   - https://rubydoc.info/gems/conversant/1.0.6/frames
+
+4. **Check for YARD parsing errors locally:**
+   ```bash
+   bundle exec yard doc --debug
+   ```
+
+5. **Verify gem metadata includes documentation_uri** (already configured in conversant.gemspec)
+
+6. **Last resort - yank and republish with bumped version:**
+   ```bash
+   gem yank conversant -v 1.0.6
+   # Update version in lib/conversant/version.rb
+   gem build conversant.gemspec
+   gem push conversant-1.0.7.gem
+   ```
+
+**Important**:
+- First-time gems can take 1-2 hours to process
+- RubyDoc.info has no official webhook/API to force processing
+- Be patient and check back the next day if needed
+
+#### Version Already Exists
+
+```bash
+# Yank the version
+gem yank conversant -v 1.0.0
+
+# Bump version number
+# Edit lib/conversant/version.rb
+
+# Republish with new version
+gem build conversant.gemspec
+gem push conversant-1.0.1.gem
+```
+
+#### Name Already Taken
+
+If "conversant" is taken, update:
+- `conversant.gemspec` (spec.name)
+- `lib/conversant/version.rb`
+- All documentation references
+
+### Debugging Tips
+
+#### Test Locally Before Publishing
+
+```bash
+# Build and install locally
+gem build conversant.gemspec
+gem install ./conversant-1.0.0.gem
+
+# Test in IRB
+irb
+> require 'conversant'
+> Conversant::VERSION
+```
+
+#### Verbose Mode
+
+```bash
+# Build with verbose output
+gem build conversant.gemspec --verbose
+
+# Push with verbose output
+gem push conversant-1.0.0.gem --verbose
+```
+
+#### Check Network Issues
+
+```bash
+# Test RubyGems API
+curl https://rubygems.org/api/v1/gems/conversant.json
+
+# Test authentication
+gem list --remote --source https://rubygems.org
+```
+
+---
+
+## Quick Reference
+
+### Essential Commands
+
+```bash
+# Development
+bundle install              # Install dependencies
+bundle exec rspec          # Run tests
+bundle exec yard doc       # Generate docs
+bundle exec yard server    # Serve docs locally
+
+# Building
+gem build conversant.gemspec    # Build gem
+gem install ./conversant-*.gem  # Test locally
+
+# Publishing
+gem signin                 # Login to RubyGems
+gem push conversant-*.gem  # Publish to RubyGems
+./publish.sh              # Automated publish script
+
+# Version Management
+gem yank conversant -v 1.0.0          # Remove version
+gem list conversant --remote --all    # List versions
+gem owner conversant                  # Check ownership
+
+# Git
+git tag -a v1.0.0 -m "Release v1.0.0"  # Create tag
+git push origin main --tags             # Push with tags
+```
+
+### Important Files
+
+```
+conversant-gem/
+├── lib/
+│   ├── conversant.rb          # Main entry point
+│   └── conversant/
+│       ├── version.rb         # Version definition
+│       ├── configuration.rb   # Configuration
+│       └── v3/               # V3 implementation
+├── spec/                      # Tests
+├── conversant.gemspec         # Gem specification
+├── Gemfile                   # Dependencies
+├── README.md                 # User documentation
+├── CHANGELOG.md              # Version history
+├── LICENSE.txt               # MIT License
+├── .gitlab-ci.yml            # CI/CD configuration
+├── .yardopts                 # Documentation settings
+└── publish.sh                # Publishing script
+```
+
+### Useful Links
+
+- **Gem on RubyGems**: https://rubygems.org/gems/conversant
+- **GitLab Repository**: https://gitlab.vnetwork.dev/gems/conversant
+- **Documentation**: https://rubydoc.info/gems/conversant
+- **RubyGems Guides**: https://guides.rubygems.org/
+- **YARD Documentation**: https://yardoc.org/
+
+### Support
+
+For issues or questions:
+- Create an issue: https://gitlab.vnetwork.dev/gems/conversant/-/issues
+- Email: tho.nguyen@vnetwork.vn
+
+---
+
+## Version History
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
+
+## License
+
+This gem is available under the [MIT License](LICENSE.txt).