Fu-Jie_openwebui-extensions/.agent/workflows/plugin-development.md

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 a single internationalized code file and bilingual documentation:

• Code (i18n):
  • plugins/{type}/{name}/{name}.py
  • The single .py file must implement internal i18n (e.g., using navigator.language or backend headers) to support multiple languages natively, rather than splitting into separate files.
• 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. This is a cumulative section. Every release MUST verify that basic core descriptions are NOT lost or overwritten by new feature lists.
  • 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): 在开头显眼位置明确描述最新的更改/更新。此部分是动态的，随版本变化。

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. Code (.py)
  2. English README (README.md)
  3. Chinese README (README_CN.md)
  4. Docs Index (docs/.../index.md)
  5. Docs Index CN (docs/.../index.zh.md)
  6. Docs Detail (docs/.../{name}.md)
  7. 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/openwebui-extensions/blob/main/plugins/{type}/{name}/README.md
     • Example: https://github.com/Fu-Jie/openwebui-extensions/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]
     • Changelog: English-only list of commits since the last release, including hashes (e.g., 896de02 docs(config): reorder antigravity model alias example).
     • Verification Status: Confirm all 7+ 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 internal i18n supported (.py) and fully functional?
• Docstrings have updated version?
• READMEs are updated and bilingual?
• Key Capabilities in READMEs still cover all legacy core features + new features?
• docs/ index and detail pages are updated?
• Root README.md is updated?
• All version numbers match exactly?
• Any non-obvious findings saved to .agent/learnings/{topic}.md?

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.

6. Knowledge Capture (Mandatory)

Whenever you discover a non-obvious behaviour, internal API contract, or workaround during plugin development, document it in .agent/learnings/{topic}.md before ending the session.

• Browse .agent/learnings/ first at the start of a session to reuse existing knowledge.
• Format: see .agent/learnings/README.md.