From 6d4d645415bba7833818935b09b48b93c73dadae Mon Sep 17 00:00:00 2001 From: Carsten Ziegeler Date: Mon, 1 Jun 2026 20:55:46 +0200 Subject: [PATCH] docs: add AGENTS.md, CLAUDE.md, and expand README Add AGENTS.md with project overview, commands, layout, dev patterns, git workflow, testing guidelines, and gotchas. Add CLAUDE.md pointing to AGENTS.md. Expand README with feature summary, baseline info, build commands, repository layout, and notes. Co-authored-by: Maia --- AGENTS.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + README.md | 74 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 171 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c9e98fe --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,97 @@ +# Project Overview + +Apache Sling Scripting Core is an OSGi bundle that provides the scripting infrastructure for Apache Sling. It manages script engine registration (via JSR-223), script caching, bindings values providers, bundled precompiled scripts, and the `SlingScript` adapter factory. The bundle runs inside an OSGi container (Felix) and integrates tightly with the Sling API, resource resolver, and servlet resolution chain. + +# Core Commands + +```bash +# Build and package (skips integration tests) +mvn clean package -DskipTests + +# Run unit tests only (maven-surefire) +mvn test + +# Run full suite including integration tests (requires OSGi container via Pax Exam) +mvn verify + +# Run a single unit test class +mvn test -Dtest=ScriptCacheImplTest + +# Run a single integration test class +mvn verify -Dit.test=HtmlScriptingIT + +# Check license headers and code style (Spotless + RAT) +mvn spotless:check apache-rat:check + +# Auto-fix Spotless formatting issues +mvn spotless:apply + +# Baseline API check (bnd) +mvn package bnd-baseline:check +``` + +No dev server — this is an OSGi bundle deployed into a Sling instance, not a standalone application. + +# Project Layout + +``` +pom.xml Maven build descriptor +bnd.bnd OSGi bundle manifest / baseline config +src/ + main/ + java/org/apache/sling/scripting/core/ + ScriptHelper.java Public API helper + ScriptNameAwareReader.java Public API reader + impl/ + DefaultSlingScript.java Core script execution logic + ScriptCacheImpl.java Script caching OSGi service + SlingScriptAdapterFactory.java Adapts resources to SlingScript + BindingsValuesProvidersByContextImpl.java Bindings aggregation + ScriptingResourceResolverProviderImpl.java + jsr223/ JSR-223 script engine management + bundled/ Bundled/precompiled script support + helper/ Internal helpers (ProtectedBindings, etc.) + servlet/ Servlet integration + resources/ OSGI-INF component descriptors + test/ + java/ Unit tests (JUnit 4 + OSGi mock / sling-mock) + resources/ Test content / OSGi configs for Pax Exam ITs +target/ + surefire-reports/ Unit test results + failsafe-reports/ Integration test results + paxexam/ Pax Exam container working directories +``` + +# Development Patterns & Constraints + +- **Java 17**, no preview features. +- **OSGi R7** component model: use `@Component`, `@Reference`, `@Activate`/`@Deactivate` from `org.osgi.service.component.annotations`. No Felix SCR annotations. +- Constructor injection is preferred for mandatory references; field injection only for optional or dynamic references. +- Metatype configuration via `@ObjectClassDefinition` in a separate `*Configuration` interface (see `ScriptCacheImplConfiguration`). +- All `impl.*` and sub-packages are internal; do not expose internal types in public API (`package-info.java` enforces `@Version`). +- Code style enforced by **Spotless** (Eclipse formatter config from parent POM). Run `mvn spotless:apply` before committing. +- License headers required on every source file; checked by Apache RAT. +- No `null` returns on public APIs — use `@Nullable`/`@NotNull` (JetBrains annotations). +- Logging via SLF4J only (`LoggerFactory.getLogger(getClass())`). + +# Git Workflow + +- Branches: feature branches off `master`; use `SLING-XXXXX` JIRA issue prefix (e.g., `SLING-12345-fix-cache-eviction`). +- Commit messages: start with the JIRA issue key — `SLING-XXXXX Fix short description`. +- PRs target `master`; CI runs via Jenkins (`Jenkinsfile` at repo root). +- Contributions require a signed Apache CLA. See https://sling.apache.org/contributing.html. + +# Testing Guidelines + +- **Unit tests**: JUnit 4, located in `src/test/java`. Use `org.apache.sling.testing.osgi-mock` and `sling-mock` for OSGi/Sling context. Mockito 5 for mocking. +- **Integration tests**: Pax Exam 4 in `src/test/java/.../it/`. Class names end in `IT`. Run with `mvn verify` (maven-failsafe). +- Place test resources under `src/test/resources/`. +- Coverage is not enforced by a gate; aim to cover OSGi lifecycle paths (`@Activate`/`@Deactivate`) explicitly. + +# Gotchas + +- Integration tests spin up a full Felix OSGi container via Pax Exam — they are slow (~minutes) and require network access to download bundles on first run. +- The `bnd.bnd` baseline file tracks exported package versions. If you change a public API without bumping the package version, `bnd-baseline:check` will fail at build time. +- `impl` packages are excluded from Javadoc generation intentionally — don't add `package-info.java` exports there without a version bump discussion. +- Both `javax.servlet` and `jakarta.servlet` APIs are dependencies; the bundle supports dual-stack environments. Don't break either import. +- Spotless reformats on `spotless:apply` but only stages changes — commit them separately. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..9a80b01 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +read @AGENTS.md diff --git a/README.md b/README.md index da10db8..3a010db 100644 --- a/README.md +++ b/README.md @@ -6,4 +6,76 @@ This module is part of the [Apache Sling](https://sling.apache.org) project. -Sling Scripting core functionality +Apache Sling Scripting Core provides the scripting infrastructure for Sling, including: + +- JSR-223 script engine registration and management +- Script execution and adaptation to `SlingScript` +- Script caching and related OSGi services +- Bindings values provider aggregation by context +- Bundled and precompiled script support + +## Current baseline + +- Java 17 (`17`) +- OSGi R7 Declarative Services annotations (`org.osgi.service.component.annotations`) +- Sling Bundle Parent `66` +- Dual servlet API support (`javax.servlet` and `jakarta.servlet`) +- Current development version: `3.0.3-SNAPSHOT` + +## Build and test + +```bash +# Build and package (skip tests) +mvn clean package -DskipTests + +# Run unit tests +mvn test + +# Run full build including integration tests (Pax Exam) +mvn verify + +# Run one unit test class +mvn test -Dtest=ScriptCacheImplTest + +# Run one integration test class +mvn verify -Dit.test=HtmlScriptingIT + +# Run formatting/license checks +mvn spotless:check apache-rat:check + +# Apply formatting fixes +mvn spotless:apply + +# Run API baseline check +mvn package bnd-baseline:check +``` + +## Repository layout + +```text +pom.xml Maven build descriptor +bnd.bnd OSGi bundle instructions +src/ + main/ + java/org/apache/sling/scripting/core/ + ScriptHelper.java + ScriptNameAwareReader.java + impl/ Internal implementation + bundled/ Bundled/precompiled script support + helper/ Internal helper utilities + jsr223/ JSR-223 integration + servlet/ Servlet integration + resources/ OSGI-INF component descriptors + test/ + java/ Unit tests and Pax Exam integration tests + resources/ Test content and configurations +target/ + surefire-reports/ Unit test reports + failsafe-reports/ Integration test reports + paxexam/ Pax Exam working directories +``` + +## Notes + +- Integration tests run in a real OSGi container via Pax Exam and are slower than unit tests. +- Internal implementation packages (`impl.*`) are intentionally not part of the public API surface.