open-webui/Fu-Jie_openwebui-extensions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a7b244602f904f190a91ec5be50cfd1867f021b0
Fu-Jie_openwebui-extensions/.agent/workflows/plugin-development.md

7.5 KiB
Raw Blame History

description
description
OpenWebUI Plugin Development & Release Workflow

OpenWebUI Plugin Development Workflow

This workflow outlines the standard process for developing, documenting, and releasing plugins for OpenWebUI. Crucially, the default goal of this workflow is "Preparation" (updating all relevant files) rather than automatic "Submission" (git commit/push), unless a release is explicitly requested.

1. Development Standards

Reference: .github/copilot-instructions.md

Bilingual Requirement

Every plugin MUST have bilingual versions for both code and documentation:

  • Code:
    • English: plugins/{type}/{name}/{name}.py
    • Chinese: plugins/{type}/{name}/{name_cn}.py (or 中文名.py)
  • README:
    • English: plugins/{type}/{name}/README.md
    • Chinese: plugins/{type}/{name}/README_CN.md

Code Structure

  • Docstring: Must include title, author, version, description, etc.
  • Valves: Use pydantic for configuration.
  • Database: Re-use open_webui.internal.db shared connection.
  • User Context: Use _get_user_context helper method.
  • Chat Context: Use _get_chat_context helper method for chat_id and message_id.
  • Debugging: Use _emit_debug_log for frontend console logging (requires SHOW_DEBUG_LOG valve).
  • Chat API: For message updates, follow the "OpenWebUI Chat API 更新规范" in .github/copilot-instructions.md.
    • Use Event API for immediate UI updates
    • Use Chat Persistence API for database storage
    • Always update both messages[] and history.messages

Commit Messages & Release Notes

  • Language: English ONLY. Do not use Chinese in commit messages or release notes.
  • Format: Conventional Commits (e.g., feat:, fix:, docs:).

2. Documentation Updates

When adding or updating a plugin, you MUST update the following documentation files to maintain consistency:

Plugin Directory

  • README.md: Update version, description, and usage.
    • Key Capabilities: MUST include ALL core functionalities and features. Do not only list new features in "What's New".
    • What's New: Explicitly describe only the latest changes/updates in a prominent position at the beginning. This section is dynamic and changes with versions.
  • README_CN.md: Update version, description, and usage.
    • 核心功能 (Key Capabilities): 必须包含所有核心功能和特性，不能只在 "What's New" 中列出。
    • 最新更新 (What's New): 在开头显眼位置明确描述最新的更改/更新。此部分是动态的，随版本变化。

Global Documentation (docs/)

  • Index Pages:
    • docs/plugins/{type}/index.md: Add/Update list item with correct version.
    • docs/plugins/{type}/index.zh.md: Add/Update list item with correct version.
  • Detail Pages:
    • docs/plugins/{type}/{name}.md: Ensure content matches README.
    • docs/plugins/{type}/{name}.zh.md: Ensure content matches README_CN.

Root README

  • README.md: Add to "Featured Plugins" if applicable.
  • README_CN.md: Add to "Featured Plugins" if applicable.

3. Version Control & Release

Reference: .github/workflows/release.yml

Version Bumping

  • Rule: Version bump is required ONLY when the user explicitly requests a release. Regular code changes do NOT require version bumps.
  • Format: Semantic Versioning (e.g., 1.0.0 -> 1.0.1).
  • When to Bump: Only update the version when:
    • User says "发布" / "release" / "bump version"
    • User explicitly asks to prepare for release
  • Agent Initiative: After completing significant changes (new features, bug fixes, or multiple code modifications), the agent SHOULD proactively ask the user if they want to prepare a new version for release.
  • Release Information Compliance: When a release is requested, the agent must generate a standard release summary (English commit title + bilingual bullet points) as defined in Section 3 & 5.
  • Default Action (Prepare Only): When performing a version bump or update, the agent should update all files locally but STOP before committing. Present the changes and the proposed Release/Commit Message to the user and wait for explicit confirmation to commit/push.
  • Consistency: When bumping, update version in ALL locations:
    1. English Code (.py)
    2. Chinese Code (.py)
    3. English README (README.md)
    4. Chinese README (README_CN.md)
    5. Docs Index (docs/.../index.md)
    6. Docs Index CN (docs/.../index.zh.md)
    7. Docs Detail (docs/.../{name}.md)
    8. Docs Detail CN (docs/.../{name}.zh.md)

Automated Release Process

  1. Trigger: Push to main branch with changes in plugins/**/*.py.
  2. Detection: scripts/extract_plugin_versions.py detects changed plugins and compares versions.
  3. Release:
    • Generates release notes based on changes.
    • Creates a GitHub Release tag (e.g., v2024.01.01-1).
    • Uploads individual .py files of changed plugins only as assets.
  4. Market Publishing:
    • Workflow: .github/workflows/publish_plugin.yml
    • Trigger: Release published.
    • Action: Automatically updates the plugin code and metadata on OpenWebUI.com using scripts/publish_plugin.py.
    • Auto-Sync: If a local plugin has no ID but matches an existing published plugin by Title, the script will automatically fetch the ID, update the local file, and proceed with the update.
    • Requirement: OPENWEBUI_API_KEY secret must be set.
    • README Link: When announcing a release, always include the GitHub README URL for the plugin:
      • Format: https://github.com/Fu-Jie/awesome-openwebui/blob/main/plugins/{type}/{name}/README.md
      • Example: https://github.com/Fu-Jie/awesome-openwebui/blob/main/plugins/filters/folder-memory/README.md

Release Content Standard

When the user confirms a release, the agent MUST follow these content standards:

  1. Commit Message:
    • Language: English ONLY.
    • Format: type(scope): description (e.g., feat(pipes): add streaming support for Copilot SDK).
    • Body: List 1-3 key changes in bullet points.
  2. Release Summary (for user review):
    • Before committing, present a "Release Draft" containing:
      • Title: e.g., Release v0.1.1: [Plugin Name] - [Brief Summary]
      • Changes: Bilingual bullet points (English/Chinese) describing the impact.
      • Verification Status: Confirm all 8+ files have been updated and synced.
  3. Internal Documentation: Ensure "What's New" sections in READMEs and docs/ match exactly the changes being released.

Pull Request Check

  • Workflow: .github/workflows/plugin-version-check.yml
  • Checks if plugin files are modified.
  • Fails if version number is not updated.
  • Fails if PR description is too short (< 20 chars).

4. Verification Checklist

Before committing:

  • Code is bilingual and functional?
  • Docstrings have updated version?
  • READMEs are updated and bilingual?
  • docs/ index and detail pages are updated?
  • Root README.md is updated?
  • All version numbers match exactly?

5. Git Operations (Agent Rules)

  1. Prepare-on-Demand: Focus on file modifications and local verification first.
  2. No Auto-Commit: Never git commit, git push, or create_pull_request automatically after file updates unless the user explicitly says "commit this" or "release now".
  3. Draft Mode: If available, use PRs as drafts first.
  4. Reference: Strictly follow the rules defined in .github/copilot-instructions.md → Git Operations (Agent Rules) section.
Reference in New Issue View Git Blame Copy Permalink