SKU Release Notes WordPress Plugin

A simplified WordPress plugin that automatically fetches and displays release notes from a public GitHub repository, designed to integrate with SKU.io's publishing system.

🎯 Overview

This plugin provides a secure, simple way to display AI-generated release notes on your WordPress website by fetching content from a public GitHub repository. No private repository access required.

✨ Key Features

• 🔒 Zero Security Risk: Fetches from public repository only (no private repo access)
• 📝 Automatic Sync: WordPress cron-based synchronization with configurable frequency
• 🎨 Custom Post Type: Dedicated release notes content type with full WordPress integration
• 🔄 Manual Sync Control: Admin interface for on-demand synchronization
• 📱 Responsive Display: Mobile-optimized templates and shortcodes
• 🔍 SEO Friendly: Clean URLs, meta tags, and sitemap integration
• 📊 Comprehensive Logging: PSR-3 compliant logging system with error tracking
• ⚙️ Cron Management: Sophisticated scheduling with cleanup and monitoring
• 🧪 Full Test Coverage: PHPUnit unit and integration tests
• 🔧 Error Handling: Robust error handling with recovery mechanisms
• 🎯 Shortcode System: Flexible display options with admin GUI builder
• 📈 Performance Optimized: Caching, duplicate prevention, and performance monitoring

🏗️ Plugin Architecture

Public GitHub Repository
https://github.com/skuio/release-notes
├── manifest.json (metadata)
├── 2025-q3-release-notes.md
└── 2025-q4-release-notes.md
           ↓ (HTTPS fetch - no authentication)
WordPress Plugin Components
├── HTTP Fetcher (caching, error handling)
├── Markdown Parser (frontmatter + HTML conversion)
├── Post Manager (WordPress post operations)
├── Admin Interface (dashboard, settings, logs)
├── Cron Manager (scheduling, cleanup)
├── Logger (PSR-3 logging, error tracking)
└── Shortcodes (flexible display options)
           ↓
WordPress Integration
├── Custom Post Type: 'sku_release_note'
├── Admin Pages: Settings, Dashboard, Logs
├── Public Templates: Archive, Single, Shortcodes
├── Cron Jobs: Sync + Cleanup
└── REST API: Status + Manual Sync
           ↓
WordPress Website
www.sku.io/release-notes/

📋 Requirements

WordPress Requirements

• WordPress 5.8 or higher
• PHP 8.0 or higher
• wp_remote_get() functionality (standard WordPress)

No External Dependencies

• ❌ No GitHub authentication tokens needed
• ❌ No SSH keys required
• ❌ No private repository access
• ✅ Simple HTTPS requests only

🚀 Installation

Method 1: WordPress Admin Upload

1. Download the plugin zip file
2. WordPress Admin → Plugins → Add New → Upload Plugin
3. Activate the plugin

Method 2: Manual Installation

1. Upload plugin folder to /wp-content/plugins/sku-release-notes/
2. Activate through WordPress admin dashboard

Method 3: WP-CLI

wp plugin install /path/to/sku-release-notes.zip --activate

⚙️ Configuration

Initial Setup

1. Navigate to WordPress Admin → Settings → Release Notes
2. Configure basic settings:
   • Repository URL: https://github.com/skuio/release-notes
   • Sync Frequency: Manual, Hourly, or Daily
   • Auto-publish: Enable/disable automatic publishing
3. Test connection and run initial sync

URL Structure

• Archive Page: /release-notes/
• Individual Notes: /release-notes/2025-q3/
• RSS Feed: /release-notes/feed/

💻 Development

File Structure

sku-release-notes/
├── sku-release-notes.php           # Main plugin file with component initialization
├── composer.json                   # PHPUnit testing dependencies
├── phpunit.xml.dist                # PHPUnit configuration
├── includes/                       # Core classes
│   ├── class-http-fetcher.php      # HTTP requests with caching & error handling
│   ├── class-markdown-parser.php   # Markdown parsing with frontmatter support
│   ├── class-post-manager.php      # WordPress post operations & sync logic
│   ├── class-admin-interface.php   # Admin dashboard with AJAX functionality
│   ├── class-shortcodes.php        # Shortcode system with builder GUI
│   ├── class-cron-manager.php      # WordPress cron scheduling & management
│   └── class-logger.php            # PSR-3 compliant logging system
├── admin/                          # Admin interface
│   ├── pages/
│   │   ├── dashboard.php           # Main dashboard with sync status
│   │   ├── settings.php            # Configuration settings
│   │   └── logs.php                # Error and activity logs
│   └── assets/
│       ├── admin.css               # Admin interface styling
│       └── admin.js                # AJAX functionality & interactions
├── public/                         # Public templates & assets
│   ├── templates/
│   │   ├── single-release-note.php # Individual release note template
│   │   ├── archive-release-notes.php # Archive listing template
│   │   └── shortcode-templates/    # Shortcode display templates
│   └── assets/
│       └── public.css              # Frontend styling with responsive design
├── tests/                          # Complete test suite
│   ├── bootstrap.php               # Test environment setup
│   ├── class-base-test-case.php    # Unit test base class
│   ├── class-wp-test-case.php      # Integration test base class
│   ├── unit/                       # Unit tests for all classes
│   │   ├── test-http-fetcher.php
│   │   ├── test-markdown-parser.php
│   │   ├── test-post-manager.php
│   │   ├── test-admin-interface.php
│   │   ├── test-shortcodes.php
│   │   ├── test-cron-manager.php
│   │   └── test-logger.php
│   ├── integration/
│   │   └── test-plugin-workflow.php # End-to-end workflow tests
│   └── fixtures/                   # Test data and mock files
│       ├── sample-manifest.json
│       └── sample-release.md
└── languages/                      # Internationalization (ready for translation)

Core Classes

The plugin is built using a modular architecture with six main components:

1. HTTP Fetcher (SKU_Release_Notes_HTTP_Fetcher)

Handles all external HTTP requests with caching and error handling.

Key Features:

• WordPress transient caching (configurable duration)
• Connection testing and validation
• Error handling with detailed logging
• Repository URL validation and security checks

// Basic usage
$http_fetcher = new SKU_Release_Notes_HTTP_Fetcher();
$manifest = $http_fetcher->fetch_manifest();
$markdown = $http_fetcher->fetch_markdown_file('release-1.0.0.md');
$connection_ok = $http_fetcher->test_connection();

2. Markdown Parser (SKU_Release_Notes_Markdown_Parser)

Converts markdown content to sanitized HTML with frontmatter support.

Key Features:

• YAML frontmatter extraction
• GitHub Flavored Markdown support
• HTML sanitization for security
• Automatic heading ID generation
• Excerpt generation and content validation

// Parse markdown with frontmatter
$parser = new SKU_Release_Notes_Markdown_Parser();
$result = $parser->parse($markdown_content);
// Returns: ['content' => $html, 'metadata' => $frontmatter, 'excerpt' => $excerpt]

3. Post Manager (SKU_Release_Notes_Post_Manager)

Orchestrates the complete sync process and manages WordPress posts.

Key Features:

• Duplicate detection and content comparison
• Automatic/manual publishing modes
• Custom post type and taxonomy registration
• Bulk operations and cleanup utilities
• Sync statistics and status reporting

4. Cron Manager (SKU_Release_Notes_Cron_Manager)

Advanced WordPress cron management for automated synchronization.

Key Features:

• Configurable sync frequencies (hourly, daily, weekly)
• Automatic cleanup of logs and old data
• Concurrent sync prevention
• Detailed cron diagnostics and status monitoring
• Manual sync triggers with logging

5. Logger (SKU_Release_Notes_Logger)

PSR-3 compliant logging system for comprehensive error tracking.

Key Features:

• Multiple log levels (emergency through debug)
• Structured logging with context data
• HTTP request logging
• Performance metrics tracking
• Email notifications for critical errors
• Log export in multiple formats (JSON, CSV, TXT)

// Logging examples
$logger = new SKU_Release_Notes_Logger();
$logger->info('Sync completed', ['posts_processed' => 5]);
$logger->log_wp_error($wp_error, 'http_fetcher');
$logger->log_performance('sync_operation', $start_time);

6. Admin Interface (SKU_Release_Notes_Admin_Interface)

Complete WordPress admin interface with AJAX functionality.

Key Features:

• Real-time sync status dashboard
• Manual sync triggers with progress feedback
• Comprehensive settings management
• Activity and error log viewing
• Bulk post operations

🔄 Synchronization Process

Data Flow

1. Fetch Manifest: Get manifest.json from public repository
2. Compare Versions: Check local vs remote release notes
3. Download New Content: Fetch any new markdown files
4. Process Content: Convert markdown to WordPress posts
5. Update Status: Log sync results and timestamps

Sync Methods

• Manual: Admin button "Sync Now"
• Scheduled: WordPress cron (hourly/daily)
• Webhook (future enhancement): GitHub webhook triggers

🎨 Customization

Template Override

Place custom templates in your theme:

your-theme/
└── sku-release-notes/
    ├── single-release-note.php
    └── archive-release-notes.php

Shortcodes

The plugin includes a comprehensive shortcode system with admin GUI builder:

Available Shortcodes

// Display latest release notes with custom options
[release_notes limit="5" layout="grid" show_date="true" show_excerpt="true"]

// Show only the latest single release
[latest_release template="minimal" show_version="true"]

// Display archive with pagination
[release_archive per_page="10" show_pagination="true"]

// Filter by tags
[release_notes tag="feature" limit="3"]

// Custom styling
[release_notes class="custom-release-notes" theme="dark"]

Shortcode Builder GUI

Access the shortcode builder in the WordPress editor:

1. Click "Add Shortcode" button in editor toolbar
2. Select shortcode type and configure options
3. Preview live output before inserting
4. Copy generated shortcode to clipboard

Template Override

Customize shortcode output by placing templates in your theme:

your-theme/sku-release-notes/
├── release-notes-list.php
├── latest-release.php
└── release-archive.php

🧪 Testing & Development

Test Suite

The plugin includes comprehensive PHPUnit tests covering all functionality:

# Install testing dependencies
composer install

# Run unit tests
vendor/bin/phpunit --testsuite=unit

# Run integration tests
vendor/bin/phpunit --testsuite=integration

# Run all tests with coverage
vendor/bin/phpunit --coverage-html=coverage/

# Test specific class
vendor/bin/phpunit tests/unit/test-http-fetcher.php

Test Coverage

• Unit Tests: All 6 core classes with 100% method coverage
• Integration Tests: End-to-end workflow validation
• Mock Framework: Brain Monkey for WordPress function mocking
• Test Fixtures: Sample data for consistent testing
• Performance Tests: Memory and execution time validation

Development Setup

# Clone repository
git clone https://github.com/skuio/wordpress-sku-release-notes.git

# Install dependencies
composer install

# Set up WordPress test environment
bash tests/bin/install-wp-tests.sh wordpress_test root '' localhost latest

# Run development server
wp server --host=localhost --port=8080

Debugging

Enable comprehensive logging for development:

// wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

// View plugin logs
$logger = sku_release_notes_logger();
$logs = $logger->get_logs(['component' => 'http_fetcher']);

📊 Admin Interface

The plugin provides a complete administrative interface with three main pages:

1. Dashboard Page

• Real-time sync status with last update timestamps
• Manual sync button with AJAX progress feedback
• Connection testing to verify repository access
• Quick statistics showing total posts and recent activity
• Cron schedule status and next scheduled sync time

2. Settings Page

• Repository Configuration: GitHub repository URL validation
• Sync Frequency: Manual, hourly, daily, or weekly scheduling
• Publishing Options: Auto-publish or save as drafts
• Cache Settings: Cache duration and cleanup options
• Display Options: Default templates and styling

3. Logs Page

• Activity Logs: All plugin operations with filtering
• Error Tracking: Detailed error logs with stack traces
• Performance Metrics: Execution times and memory usage
• Export Options: Download logs in JSON, CSV, or TXT format
• Log Management: Clear logs and adjust retention settings

AJAX Functionality

• Live sync progress with real-time status updates
• Connection testing without page refresh
• Bulk operations on release note posts
• Log filtering and searching without page reload

🔒 Security Features

Public-Only Access

• ✅ No authentication tokens required
• ✅ No private repository access
• ✅ Standard HTTPS requests only
• ✅ No sensitive credentials stored

Content Safety

• ✅ Markdown content sanitized before publication
• ✅ Admin-only plugin configuration access
• ✅ Rate limiting on sync operations
• ✅ Error logging for troubleshooting

📈 Performance

Caching Strategy

• HTTP Responses: 10-minute cache for manifest requests
• Processed Content: Cache until remote content changes
• WordPress Integration: Leverage existing WordPress caching

Optimization

• Selective Sync: Only fetch changed content
• Background Processing: Non-blocking sync operations
• Lazy Loading: Efficient content loading for archives

🚨 Troubleshooting

Common Issues

"Connection Failed" Error

• Check internet connectivity
• Verify repository URL is correct
• Ensure WordPress can make external HTTP requests

"No Release Notes Found" Error

• Verify public repository contains manifest.json
• Check file naming and structure in repository
• Confirm manifest.json format is correct

Sync Not Working

• Check WordPress cron functionality
• Verify admin user permissions
• Review sync logs for specific errors

📝 API Reference

Public Repository Structure

The plugin expects this structure in the public GitHub repository:

repository/
├── manifest.json           # Required: Release metadata
├── release-1.0.0.md        # Release note files
├── release-1.1.0.md
└── release-2.0.0.md

Manifest Format (manifest.json)

{
  "version": "1.0",
  "last_updated": "2025-01-15T10:00:00Z",
  "repository": "https://github.com/skuio/release-notes",
  "release_notes": [
    {
      "filename": "release-1.0.0.md",
      "title": "Version 1.0.0 - Initial Release",
      "date": "2025-01-15",
      "version": "1.0.0",
      "summary": "Initial release with core functionality",
      "tags": ["feature", "initial"]
    }
  ]
}

Release Note Format (Markdown with Frontmatter)

---
title: Version 1.0.0 - Initial Release
version: 1.0.0
date: 2025-01-15
tags: [feature, initial]
author: Development Team
---

# Version 1.0.0 - Initial Release

## New Features
- Feature A
- Feature B

## Bug Fixes
- Fixed issue X
- Resolved problem Y

WordPress Functions

// Get plugin instance
$plugin = sku_release_notes();

// Trigger manual sync
$result = sku_release_notes_trigger_sync();

// Get sync status
$status = sku_release_notes_get_sync_status();

// Access logger
$logger = sku_release_notes_logger();
$logger->info('Custom log message', ['context' => 'data']);

// Access components
$http_fetcher = $plugin->get_component('http_fetcher');
$post_manager = $plugin->get_component('post_manager');
$cron_manager = $plugin->get_component('cron_manager');

WordPress Hooks

// Plugin activation/deactivation
do_action('sku_release_notes_activated');
do_action('sku_release_notes_deactivated');

// Sync events
do_action('sku_release_notes_sync_started');
do_action('sku_release_notes_sync_completed', $result);
do_action('sku_release_notes_sync_failed', $error);

// Content processing
apply_filters('sku_release_notes_parsed_content', $content, $metadata);
apply_filters('sku_release_notes_post_data', $post_data, $release_data);

// Logging
apply_filters('sku_release_notes_min_log_level', 'info');
do_action('sku_release_notes_log_recorded', $log_entry);

📄 License

GPL v2 or later (standard WordPress plugin license)

🤝 Support

• Documentation: Complete setup and troubleshooting guides
• Issue Tracking: GitHub repository issues
• WordPress Standards: Follows WordPress plugin guidelines

---

This plugin is designed to work with the SKU.io release notes publishing system and fetches content from public repositories only.