This is an automated email from the ASF dual-hosted git repository.
cziegeler pushed a commit to branch master
in repository
https://gitbox.apache.org/repos/asf/sling-org-apache-sling-scripting-spi.git
The following commit(s) were added to refs/heads/master by this push:
new 747381d docs: add AGENTS.md, CLAUDE.md, and expand README (#4)
747381d is described below
commit 747381d37ce7306ae4aebc1f6a85cd5d2d3850a9
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 10:06:33 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#4)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 23 +++++++++++++---
3 files changed, 112 insertions(+), 4 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..e4fe6a7
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,92 @@
+# Project Overview
+
+Apache Sling Scripting SPI is a Java OSGi bundle that defines the service
provider interfaces for the Sling scripting layer. It provides two packages:
`org.apache.sling.scripting.spi.bundle` (interfaces for bundled/precompiled
render units) and `org.apache.sling.api.resource.type` (a `ResourceType` value
object for parsing Sling resource type strings). This is a pure API/SPI library
with no runtime logic — consumers implement the interfaces, providers discover
them via OSGi services.
+
+# Core Commands
+
+```bash
+# Build and package
+mvn clean install
+
+# Compile only
+mvn compile
+
+# Run full test suite
+mvn test
+
+# Run a single test class
+mvn test -Dtest=ResourceTypeTest
+
+# Run SpotBugs static analysis
+mvn spotbugs:check
+
+# Run bnd baseline check (API compatibility)
+mvn verify
+
+# Run Spotless formatter check
+mvn spotless:check
+
+# Apply Spotless formatting
+mvn spotless:apply
+```
+
+No dev server — this is a library bundle deployed into an OSGi container
(Apache Felix / Sling Launchpad).
+
+# Project Layout
+
+```
+pom.xml Maven build; parent = sling-bundle-parent:66
+src/
+ main/java/
+ org/apache/sling/
+ scripting/spi/bundle/ Core SPI interfaces
+ BundledRenderUnit.java Executed script/precompiled unit contract
+ BundledRenderUnitCapability.java OSGi capability descriptor interface
+ BundledRenderUnitFinder.java Lookup service interface
+ TypeProvider.java Associates a bundle with resource types
+ package-info.java OSGi package version annotation
+ api/resource/type/
+ ResourceType.java Value object for parsing resource type strings
+ package-info.java OSGi package version annotation
+ test/java/
+ org/apache/sling/api/resource/type/
+ ResourceTypeTest.java JUnit 4 tests for ResourceType
+target/ Maven output (do not edit)
+ baseline/ bnd API baseline snapshot
+```
+
+# Development Patterns & Constraints
+
+- **Java 17** (`sling.java.version=17` in `pom.xml`).
+- **OSGi annotations**: use `org.osgi.annotation.versioning` (`@ConsumerType`,
`@ProviderType`) on all public interfaces. Never use Felix SCR annotations.
+- **Nullability**: annotate all public API with `@NotNull` / `@Nullable` from
`org.jetbrains.annotations`.
+- **Servlet API**: this bundle supports both `javax.servlet` (deprecated) and
`jakarta.servlet`. New methods must target Jakarta; provide `javax.servlet`
overloads only for backward compatibility and mark them `@Deprecated`.
+- **Package versioning**: bump the `@Version` in `package-info.java` on any
API change. Verify with `mvn verify` (bnd baseline fails the build on
incompatible changes).
+- **No implementations here**: this repo is SPI only. Do not add concrete
implementations.
+- Code is formatted via Spotless (enforced in CI). Run `mvn spotless:apply`
before committing.
+- 4-space indentation, no tabs.
+
+# Git Workflow
+
+- Mirror of the Apache Sling Git repository at
`https://gitbox.apache.org/repos/asf/sling-org-apache-sling-scripting-spi.git`.
+- Branching: `master` is the main branch. Feature work goes on topic branches;
merge via PR to the GitHub mirror.
+- Commit messages: short imperative subject line, reference JIRA ticket if
applicable (`SLING-XXXXX`).
+- PRs require passing CI (Jenkins via `Jenkinsfile`) before merge.
+- Do not push directly to `master`.
+
+# Testing Guidelines
+
+- Framework: **JUnit 4** (`junit:junit` test-scoped dependency).
+- Test classes live under `src/test/java/` mirroring the main source package
structure.
+- Run all tests: `mvn test`
+- Run one class: `mvn test -Dtest=ClassName`
+- Surefire reports land in `target/surefire-reports/`.
+- No coverage tooling is configured; do not add one without discussion.
+- Since this is a pure SPI bundle, tests focus on value objects
(`ResourceType`). Interface tests are not required.
+
+# Gotchas
+
+- **Baseline failures**: any change to a public API (method signature, return
type, new required method on a `@ConsumerType`) will fail `mvn verify` via the
bnd baseline plugin. Bump the affected package version in its
`package-info.java` first.
+- **Dual servlet APIs**: `BundledRenderUnit.eval(...)` has two overloads —
Jakarta (preferred) and javax (deprecated). The Jakarta default method
delegates to the javax abstract method for backward compat. New consumers
should implement the javax abstract method; it is called by the Jakarta
default. Do not remove the javax overload.
+- **No OSGi runtime in tests**: tests run in plain JVM; do not reference
`BundleContext` or OSGi framework APIs in test code without mocking.
+- The `target/` directory contains a committed baseline JAR snapshot
(`target/baseline/`). This is intentional — managed by
bnd-baseline-maven-plugin, not by hand.
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 8b3cf49..208f20d 100644
--- a/README.md
+++ b/README.md
@@ -6,10 +6,25 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The bundle currently provides the `org.apache.sling.scripting.spi.bundle` SPI,
which allows the
-[Apache Sling Servlets
Resolver](https://github.com/apache/sling-org-apache-sling-servlets-resolver)
and the
-[Apache Sling Scripting
Core](https://github.com/apache/sling-org-apache-sling-scripting-core) to wire
up and
-execute bundled scripts (precompiled or not) in order to render HTTP requests.
+This bundle provides:
+
+- `org.apache.sling.scripting.spi.bundle`: SPI interfaces used by the
+ [Apache Sling Servlets
Resolver](https://github.com/apache/sling-org-apache-sling-servlets-resolver)
and
+ [Apache Sling Scripting
Core](https://github.com/apache/sling-org-apache-sling-scripting-core) to
discover and
+ execute bundled scripts (precompiled or interpreted) for request rendering.
+- `org.apache.sling.api.resource.type`: a `ResourceType` value object for
parsing Sling resource type strings.
+
+The API is built for Java 17 and supports both Jakarta Servlet API (preferred)
and legacy `javax.servlet` API
+for backward compatibility.
+
+## Build and verification
+
+```bash
+mvn clean install
+mvn test
+mvn verify
+mvn spotless:check
+```
## Integration Tests
