SWIP-12 design + UITemplateInitializer auto-discovery & dev hot-reload

[wu-sheng]

SWIP-12 design + UITemplateInitializer extensibility

This PR bundles three related changes that together unlock future mini-program monitoring work:

1. SWIP-12 design doc (docs/en/swip/SWIP-12.md)
Proposes WeChat & Alipay Mini-Program monitoring as a new pair of Layer values. Covers SDK alignment (histogram bucket unit), native-trace SegmentListener SPI, entity model, layer partitioning, dashboards layout, and MAL/OAL scope split. Still a design-only proposal — implementation lands in follow-up PRs.

2. UITemplateInitializer extensibility + dev hot-reload

• UI_TEMPLATE_FOLDER is now computed from Layer.values() + "custom" at class-init time. Adding a new Layer enum value is enough — drop a ui-initialized-templates/<layer-name-lowercased>/ folder on disk and it's scanned on the next boot. Removes the prior hardcoded allowlist that was easy to miss.
• SW_UI_TEMPLATE_FORCE_RELOAD env var switches the initializer from addIfNotExist to a new addOrReplace helper on UITemplateManagementService. When true, shipped templates overwrite any seeded copy every boot — so dev/extension edits show up after a simple OAP restart without wiping storage. Unset / false preserves the production behavior where operator UI edits persist.
• UITemplateCheckerTest updated to tolerate missing folders (several Layer values have no template folders today).

3. new-monitoring-feature skill (.claude/skills/new-monitoring-feature/SKILL.md)
A wiring map for contributors adding a new layer: which extension point handles which signal (OAL / MAL / LAL / SpanListener / SegmentListener), where contracts live, UI template + submodule touchpoints, and cross-cutting traps.

• If this is non-trivial feature, paste the links/URLs to the design doc. — docs/en/swip/SWIP-12.md

• Update the documentation to include this new feature. — SWIP doc + readme index updated

• Tests(including UT, IT, E2E) are added to verify the new feature. — UITemplateCheckerTest updated for auto-discovery

• If it's UI related, attach the screenshots below. — N/A; no UI dashboards land in this PR (follow-up)

• If this pull request closes/resolves/fixes an existing issue, replace the issue number. Closes #.

• Update the CHANGES log. — deferred until mini-program monitoring implementation lands

[Copilot]

Pull request overview

This PR introduces SWIP-12 (mini-program monitoring design), improves UI template initialization by auto-discovering template folders from Layer.values(), and adds a dev-oriented hot-reload mode for shipped UI templates.

Changes:

• Add SWIP-12 design doc and index it in the SWIP readme.
• Auto-discover UI template folders from Layer enums (+ custom) and add SW_UI_TEMPLATE_FORCE_RELOAD to overwrite seeded templates on restart.
• Update UITemplateCheckerTest to skip layers that don’t have an on-disk template folder.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
oap-server/server-starter/src/test/java/org/apache/skywalking/oap/server/starter/UITemplateCheckerTest.java	Test now tolerates missing template folders to match initializer behavior.
oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/management/ui/template/UITemplateManagementService.java	Adds addOrReplace to support force-reload behavior.
oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/management/ui/template/UITemplateInitializer.java	Auto-discovers folders from Layer.values() and supports force reload via env var.
docs/en/swip/readme.md	Updates next SWIP number and links SWIP-12.
docs/en/swip/SWIP-12.md	New SWIP-12 design proposal document.
.claude/skills/new-monitoring-feature/SKILL.md	New contributor “wiring map” for adding a monitoring feature/layer.

Comments suppressed due to low confidence (2)

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/management/ui/template/UITemplateInitializer.java:93

• folder.toLowerCase() uses the JVM default locale, which can produce incorrect folder names under certain locales (e.g., Turkish 'IOS' -> 'ıos') and make shipped templates undiscoverable. Please lower-case using Locale.ROOT (or precompute UI_TEMPLATE_FOLDER as already-lowercased with Locale.ROOT).

                File[] templateFiles = ResourceUtils.getPathFiles("ui-initialized-templates/" + folder.toLowerCase());
                for (File file : templateFiles) {

oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/management/ui/template/UITemplateInitializer.java:98

• With UI_TEMPLATE_FOLDER now containing every Layer, ResourceUtils.getPathFiles(...) will throw/catch a FileNotFoundException once per missing template folder on every boot. Since exceptions are relatively expensive (stack trace capture) and this is expected control flow, consider checking ClassLoader.getResource(path) (or adding a non-throwing helper in ResourceUtils) and skipping when null instead of relying on exceptions.

        for (String folder : UITemplateInitializer.UI_TEMPLATE_FOLDER) {
            try {
                File[] templateFiles = ResourceUtils.getPathFiles("ui-initialized-templates/" + folder.toLowerCase());
                for (File file : templateFiles) {
                    initTemplate(file);
                }
            } catch (FileNotFoundException e) {
                log.debug("No such folder of path: {}, skipping loading UI templates", folder);
            }

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.