feat(best-practices): add resource-change-listener expert skill #167
Open
Himanich wants to merge 2 commits into
Open
feat(best-practices): add resource-change-listener expert skill #167Himanich wants to merge 2 commits into
Himanich wants to merge 2 commits into
Conversation
Introduces best-practices/resource-change-listener/SKILL.md as the second expert skill subdirectory, replacing the flat references/resource-change-listener.md file. Single-file SKILL.md (no split needed — one target architecture: lightweight listener + JobConsumer). Covers: - Two interface variants (ResourceChangeListener vs ExternalResourceChangeListener) - Three CS-specific constraints (no Session in onChange, service-user resolver in consumer, filter at registration) - Classification: skip / R1-R5 / R0+R1-R5 based on source type - Complete before/after example (legacy JCR EventListener → RCL + JobConsumer) - R0: convert from javax.jcr.observation.EventListener or resource-topic EventHandler - R1: keep onChange lightweight, per-change try/catch mandatory - R2: JobConsumer with resolver.commit() guidance, PersistenceException handling, author-only SlingSettingsService guard - R3: ResourceChangeListener vs ExternalResourceChangeListener decision, multi-pod fan-out warning - R4: full import diff - R5: Repoinit + ServiceUserMapperImpl.amended config - Review checklist (cross-cutting + listener + consumer + configuration) - Troubleshooting fingerprints with grep-able log strings - Common pitfalls (silent registration, topic mismatch, external-by-default, missing commit) - Modern alternatives decision matrix Cross-cutting fix (scheduler): - Remove /system/console URL references from scheduler troubleshooting; describe component runtime state instead. Felix Web Console is not accessible on AEMaaCS production — use Developer Console in Cloud Manager. Same approach applied to RCL troubleshooting. Deprecation notice added to references/resource-change-listener.md pointing to the new expert skill. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…eedback Apply reviewer feedback to bring RCL skill to expert-skill standards for AEMaaCS: - Soften absolute "all business logic must be offloaded" wording in Overview and R1; allow small in-memory operations (metrics, lightweight filtering, enqueue) in onChange() while keeping the strong rule against repository access, I/O, and expensive computation - Add AEM Eventing to Modern Alternatives as the supported path for notifying external systems (Adobe I/O Events, App Builder, webhooks); RCL clarified as in-process pattern - Add cluster-coordination warning to author-only consumer pattern: run mode check does not guarantee single execution on author clusters - Strengthen ExternalResourceChangeListener guidance with explicit pre-selection checklist (idempotency, duplicate-processing tolerance, intentional per-node execution) - Soften "not recommended" wording for javax.jcr.observation.EventListener; preserve escalation path (Adobe support case for documented platform needs) - Add PROPERTY_NAMES_HINT semantics note: optimization hint, not a contract; application code must validate actual ResourceChange data - Add Common Pitfalls: event storms from broad PATHS, recursive self-triggering when consumer writes to observed subtree - Add Troubleshooting rows: repeated self-triggering, excessive job volume - Add Expert Guidance section: idempotency principles for distributed AEMaaCS (event batching, retries, cluster coordination, derive state from repository) - Add note that PATHS are chosen by the implementer from the business scope; do not ask customer for raw PATHS syntax Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Himanich
requested review from
abhishekgarg18,
akankshajain18,
pkumargaddam and
rombert
as code owners
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds resource-change-listener as the second expert skill subdirectory under plugins/aem/cloud-service/skills/best-practices/, following the structural pattern established by (scheduler/).
Related Issue
Part of the best-practices expert-skill decomposition initiative.
Motivation and Context
The flat references/*.md files under best-practices/ were migration-focused only. Decomposing each pattern into a standalone expert skill subdirectory
How Has This Been Tested?
Validation done:
Reviewed against the original references/resource-change-listener.md to confirm content parity
Audited against AEMaaCS-specific best practices: Repoinit-only service users, multi-pod fan-out for external listeners, no getAdministrativeResourceResolver, lightweight onChange(), resolver.commit() for write-side consumers, SlingSettingsService author guard with single-execution warning, idempotency guidance for retries and clustered author
Screenshots (if appropriate):
Types of changes
Checklist: