Fu-Jie_openwebui-extensions/docs/release-workflow.md

Plugin Release Workflow

This document describes the workflow for releasing plugin updates.

---

Overview

The release workflow consists of the following components:

1. CHANGELOG.md - Records all notable changes
2. Version Extraction Script - Automatically extracts plugin versions
3. GitHub Actions Workflows - Automates the release process

---

Automatic Release Process ⭐

When a plugin update PR is merged to main branch, the release process is triggered automatically:

PR Merge Requirements

PRs that modify plugin files must meet the following conditions to merge:

1. ✅ Version must be updated - The plugin's version field must be changed
2. ✅ PR description must contain update notes - At least 20 characters of description

If these conditions are not met, the PR check will fail and cannot be merged.

Automatic Release Contents

After successful merge, the system will automatically:

1. 🔍 Detect version changes (compared to last release)
2. 📝 Generate release notes (with update content and commit history)
3. 📦 Create GitHub Release (with downloadable plugin files)
4. 🏷️ Auto-generate version number (format: vYYYY.MM.DD-run_number)

Release Includes

• plugins_release.zip - All updated plugin files packaged
• plugin_versions.json - All plugin version information (JSON format)
• Release Notes - Includes:
  • List of new/updated plugins
  • Related commit history
  • Complete plugin version table
  • Installation instructions

---

Release Process

Step 1: Update Plugin Version

When you make changes to a plugin, you must update the version number:

"""
title: My Plugin
author: Fu-Jie
version: 0.2.0  # <- Must update this!
...
"""

Step 2: Create PR with Update Notes

Add update notes in your PR description (at least 20 characters):

## Changes

- Added XXX feature
- Fixed YYY issue
- Improved ZZZ performance

Step 3: Merge PR

After checks pass, merge the PR to main branch - the system will automatically create a Release.

---

Manual Release (Optional)

In addition to automatic release, you can also trigger manually:

Option A: Manual Trigger

1. Go to GitHub Actions → "Plugin Release / 插件发布"
2. Click "Run workflow"
3. Fill in the details:
   • version: e.g., v1.0.0 (leave empty for auto-generation)
   • release_title: e.g., "Smart Mind Map Major Update"
   • release_notes: Additional notes in Markdown
   • prerelease: Check if this is a pre-release

Option B: Tag-based Release

# Create and push a version tag
git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

---

Version Numbering

We follow Semantic Versioning:

• MAJOR: Breaking changes
• MINOR: New features, backwards compatible
• PATCH: Bug fixes

Examples

Change Type	Version Change
Bug fix	0.1.0 → 0.1.1
New feature	0.1.1 → 0.2.0
Breaking change	0.2.0 → 1.0.0

---

GitHub Actions Workflows

release.yml

Triggers:

• ⭐ Push to main branch with plugins/**/*.py changes (auto-release)
• Manual workflow dispatch
• Push of version tags (v*)

Actions:

1. Detects version changes compared to last release
2. Collects updated plugin files
3. Generates release notes (with commit history)
4. Creates GitHub Release (with downloadable attachments)

plugin-version-check.yml

Trigger:

• Pull requests that modify plugins/**/*.py

Actions:

1. Compares plugin versions between base and PR
2. Checks if version was updated
3. Checks if PR description is detailed enough
4. ❌ Fails if no version update detected
5. ⚠️ Fails if PR description is too short

---

Scripts

extract_plugin_versions.py

Usage:

# Output to console
python scripts/extract_plugin_versions.py

# Output as JSON
python scripts/extract_plugin_versions.py --json

# Output as Markdown table
python scripts/extract_plugin_versions.py --markdown

# Compare with previous version
python scripts/extract_plugin_versions.py --compare old_versions.json

# Save to file
python scripts/extract_plugin_versions.py --json --output versions.json

---

Best Practices

1. Always update version numbers when making functional changes (required)
2. Write clear PR descriptions describing what changed and why (required)
3. Test locally before creating a PR
4. Use pre-releases for testing new features
5. Reference issues in PR descriptions

---

Installing All Plugins to Your Instance

After a release, you can quickly install all plugins to your local OpenWebUI instance:

# Clone the repository
git clone https://github.com/Fu-Jie/openwebui-extensions.git
cd openwebui-extensions

# Create .env file with your API key
echo "api_key=sk-your-api-key-here" > scripts/.env

# Install all plugins at once
python scripts/install_all_plugins.py

For detailed instructions, see Deployment Guide.

---

Author

Fu-Jie
GitHub: Fu-Jie/openwebui-extensions