Merge pull request dmm-com#1644 from syucream/fix/describe-plugin-hooks

docs: clarify interaction between hooks and overrides in plugin system

Author: hinashi

airone/lib/plugin_dispatch.py

@@ -29,6 +29,11 @@ class PluginOverrideMixin:
     If found, the request is dispatched to the plugin handler instead
     of the default ViewSet implementation.
 
+    When an override is active, the normal ViewSet processing — including
+    Job creation and hook invocation — is skipped entirely. The override
+    handler is responsible for the full operation. If the handler needs
+    hooks (@entry_hook) to fire, it must create a Job internally.
+
     Usage:
         class EntryAPI(PluginOverrideMixin, viewsets.ModelViewSet):
             ...

plugin/examples/pagoda-cross-entity-plugin/README.md

@@ -333,6 +333,17 @@ Entity binding is now done via configuration:
 export BACKEND_PLUGIN_ENTITY_OVERRIDES='{"42": {"plugin": "cross-entity-sample", "operations": ["retrieve"], "params": {}}}'
 ```
 
+## Interaction Between Hooks and Overrides
+
+When an override handler is active for an entity/operation, the normal ViewSet processing flow (including Job creation) is bypassed. This has implications for `@entry_hook` hooks:
+
+- **Override uses Job internally**: If your override handler creates a Job (e.g., `job_register_entry`) to perform the actual operation, hooks registered via `@entry_hook` **will fire** as normal, because the Job triggers the same code path that fires hooks.
+- **Override does NOT use Job**: If your override handler performs the operation directly (e.g., calling `Entry.objects.create()` or manipulating models without a Job), hooks **will NOT fire**, because the hook invocation is tied to the Job execution path.
+
+This is by design — an override replaces the entire operation, so the plugin author decides whether to go through the standard Job pipeline or not.
+
+The sample `handlers.py` in this plugin uses the Job-based pattern, so hooks will fire for overridden operations.
+
 ## Development Notes
 
 - Handlers are registered during plugin initialization via the override registry

plugin/sdk/pagoda_plugin_sdk/override.py

@@ -83,6 +83,12 @@ def handle_create(self, context: OverrideContext):
         - entry: Entry instance (for retrieve/update/delete)
         - data: Request data dict (for create/update)
         - params: Plugin-specific parameters from configuration
+
+    Note:
+        Override handlers bypass the normal ViewSet -> Job flow. If your handler
+        creates a Job internally (e.g., job_register_entry), hooks registered via
+        @entry_hook will still fire. If your handler performs the operation directly
+        without a Job, hooks will not execute.
     """
     if operation.lower() not in _VALID_OPERATIONS:
         raise ValueError(