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-jcr-resource.git
The following commit(s) were added to refs/heads/master by this push:
new cd3a450 docs: add AGENTS.md, CLAUDE.md and expand README (#54)
cd3a450 is described below
commit cd3a45005e7b26e52128896e4e49a27d4d5444e5
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 07:31:09 2026 +0200
docs: add AGENTS.md, CLAUDE.md and expand README (#54)
Add AGENTS.md with full project overview, commands, layout, patterns,
testing guidelines, and gotchas for AI coding agents. Add CLAUDE.md
redirecting to AGENTS.md. Expand README with build/test commands,
development checks, repository layout, and key technical details.
Also correct the README title and module description.
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 118 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 66 +++++++++++++++++++++++++++++++++--
3 files changed, 183 insertions(+), 2 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..872314e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,118 @@
+# Project Overview
+
+`org.apache.sling.jcr.resource` is an OSGi bundle that implements Sling's
JCR-backed resource provider and resolver internals. It maps JCR
nodes/properties to Sling `Resource` objects, handles session/provider-state
lifecycle, exposes JCR-backed `ValueMap` implementations, and emits
resource-change events from JCR observation. The bundle runs in an OSGi
container with a JCR repository (typically Jackrabbit Oak).
+
+# Core Commands
+
+```bash
+# Build and package (skips tests)
+mvn clean package -DskipTests
+
+# Full build with tests
+mvn clean install
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=JcrResourceProviderTest
+
+# Run a single test method
+mvn test -Dtest=JcrValueMapTest#testPutMultipleValues
+
+# Apply Spotless code formatting (inherited from sling-bundle-parent)
+mvn spotless:apply
+
+# Check formatting without applying
+mvn spotless:check
+
+# License header check (Apache RAT)
+mvn apache-rat:check
+
+# API baseline check
+mvn bnd-baseline:baseline
+```
+
+No dev server — this is a pure OSGi bundle deployed into a Sling/Felix runtime.
+
+# Project Layout
+
+```
+pom.xml Maven build descriptor
+bnd.bnd OSGi manifest extras (optional scripting
import, conditional packages, Sling namespaces/nodetypes)
+src/
+ main/
+ java/org/apache/sling/jcr/resource/
+ api/
+ JcrResourceChange.java Public API type for JCR-backed
resource change details
+ JcrResourceConstants.java Public constants for JCR resource
handling
+ internal/
+ JcrListenerBaseConfig.java OSGi config model for JCR observation
listener behavior
+ JcrResourceListener.java JCR observation listener and event
bridge
+ JcrModifiableValueMap.java Writable ValueMap backed by a JCR Node
+ JcrValueMap.java Read-only ValueMap backed by JCR
properties
+ JcrSystemUserValidator.java Validates service-user principal names
+ NodeUtil.java JCR node utility helpers
+ scripting/
+ JcrObjectsBindingsValuesProvider.java Exposes JCR objects to script
bindings
+ helper/
+ JcrPropertyMapCacheEntry.java Property map caching
+ AccessLogger.java Structured access logging helpers
+ Converter.java and *Converter.java Type conversion helpers
(Boolean, Date, Calendar, Number, String, ZonedDateTime)
+ jcr/
+ JcrResourceProvider.java Main JCR ResourceProvider
implementation
+ JcrProviderStateFactory.java Session/provider-state lifecycle
factory
+ JcrProviderState.java Provider state holder
+ JcrItemResourceFactory.java Creates Resource from JCR Item
+ JcrItemResource.java Base resource wrapping a JCR Item
+ JcrNodeResource.java Resource wrapping a JCR Node
+ JcrPropertyResource.java Resource wrapping a JCR Property
+ JcrNodeResourceIterator.java Iterator over node-backed
resources
+ JcrNodeResourceMetadata.java Metadata support for node
resources
+ BasicQueryLanguageProvider.java Query language provider
integration
+ BinaryDownloadUriProvider.java Direct binary download URI support
+ ContextUtil.java Context/resource-resolver utility
methods
+ resources/SLING-INF/nodetypes/ CND node-type definitions (folder,
resource, vanitypath, redirect, mapping)
+ test/
+ java/… JUnit 4 tests mirroring the main package
structure
+target/ Build output (ignored by git)
+```
+
+# Development Patterns & Constraints
+
+- **Java version**: source/target compatibility Java 8
(`sling.java.version=8`).
+- **OSGi annotations**: use `org.osgi.service.component.annotations` (R6/R7).
Do not use Felix SCR annotations.
+- **Nullability**: annotate with `org.jetbrains.annotations` (`@NotNull`,
`@Nullable`) on public API where applicable.
+- **License header**: every `.java` and `.xml` source file must carry the
Apache 2.0 license block. Run `mvn apache-rat:check` to verify.
+- **Formatting**: Spotless is enforced by the parent POM. Run `mvn
spotless:apply` before committing. 4-space indentation; no tabs.
+- **Import order**: follow the Spotless-enforced order (static imports →
`javax.*` → `java.*` → third-party → internal).
+- **Internal API**: everything under `*.internal.*` is private API. Do not
expose internal types in public OSGi service contracts.
+- **Public API compatibility**: types in `org.apache.sling.jcr.resource.api`
are baseline-checked; keep semantic versioning constraints in mind.
+- **OSGi descriptors**: generated at build time from annotations/bnd; do not
hand-edit generated `OSGI-INF` files.
+- **Optional scripting API**: `org.apache.sling.scripting.api` is imported
with `resolution:=optional`; guard scripting-dependent paths.
+
+# Git Workflow
+
+- Default branch: `master`.
+- Feature branches: `feature/<jira-id>-short-description` or
`fix/<jira-id>-short-description`.
+- Commit messages: short imperative subject line; reference JIRA issue
(`SLING-XXXXX`) where applicable.
+- PRs target `master`. CI runs Maven build + tests via Jenkins (`Jenkinsfile`
at repo root).
+- See [CONTRIBUTING.md](CONTRIBUTING.md) for Apache CLA and code-review
process.
+
+# Testing Guidelines
+
+- **Framework**: JUnit 4 (`junit:junit`), Mockito 5, Hamcrest 2, JMock.
+- **Sling testing**: `org.apache.sling.testing.sling-mock.junit4` +
`sling-mock-oak` for integration-style tests against an in-memory Oak
repository.
+- **Test location**: `src/test/java/` mirroring the main package structure.
Test classes end with `Test`.
+- **Shared base classes**: `JcrItemResourceTestBase`,
`SlingRepositoryTestBase` — extend these for tests needing a live JCR session.
+- **Coverage report**: `mvn test jacoco:report` (JaCoCo is inherited from
parent POM).
+- Do not use `@RunWith(MockitoJUnitRunner.class)` and `@Rule MockitoRule`
together in the same class.
+
+# Gotchas
+
+- **Oak version pinned**: `oak.version=1.44.0` is the minimum for
`JackrabbitNode.getPropertyOrNull`. Bumping below 1.44.0 breaks compilation.
+- **sling-mock exclusion**: `org.apache.sling.testing.sling-mock.junit4` must
exclude `org.apache.sling.jcr.resource` to avoid classpath conflicts with the
bundle under test (configured in `pom.xml`).
+- **`bnd-baseline`**: baseline checks enforce semantic versioning for exported
packages; API changes may require package version updates.
+- **Conditional packages**: `org.apache.jackrabbit.util` and
`org.apache.jackrabbit.name` are inlined via `-conditionalpackage` in
`bnd.bnd`; do not add them as explicit `Import-Package` entries.
+- **Scripting API is optional**: `org.apache.sling.scripting.api` is optional
at runtime; code must handle its absence.
+- **No standalone runner**: the bundle cannot run standalone; deploy into
Sling/Felix or use `sling-mock-oak` for repository-backed tests.
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 c7256fa..d26adca 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,70 @@
 [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-org-apache-sling-jcr-resource/job/master/) [](https://ci-builds.apache.org/job/Sling/job/modules/job/sling-org-apache-sling-
[...]
-# Apache Sling JCR Resource Resolver
+# Apache Sling JCR Resource
This module is part of the [Apache Sling](https://sling.apache.org) project.
-This bundle provides the JCR based Resource Resolver.
+This bundle provides Sling's JCR-backed resource provider and resolver
internals.
+It maps JCR nodes and properties to Sling `Resource` objects, handles
provider/session lifecycle, supports query and binary download integrations,
and emits resource change events from JCR observation.
+
+## Build and test
+
+```bash
+# Build and package (skip tests)
+mvn clean package -DskipTests
+
+# Full build (including tests)
+mvn clean install
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=JcrResourceProviderTest
+
+# Run a single test method
+mvn test -Dtest=JcrValueMapTest#testPutMultipleValues
+```
+
+## Development checks
+
+```bash
+# Apply formatting
+mvn spotless:apply
+
+# Check formatting
+mvn spotless:check
+
+# Verify license headers
+mvn apache-rat:check
+
+# Check API baseline compatibility
+mvn bnd-baseline:baseline
+```
+
+## Repository layout
+
+```text
+pom.xml Maven build descriptor
+bnd.bnd OSGi metadata and package instructions
+src/
+ main/
+ java/org/apache/sling/jcr/resource/
+ api/ Public API (for example JcrResourceChange,
constants)
+ internal/ Internal implementation
(resource/provider/listener/value map helpers)
+ helper/jcr/ Core JCR ResourceProvider and resource
wrappers
+ scripting/ Optional scripting bindings integration
+ resources/SLING-INF/nodetypes/
+ Sling/JCR node type definitions
+ test/
+ java/ JUnit 4 tests (Mockito, Hamcrest, JMock,
sling-mock-oak)
+```
+
+## Key technical details
+
+- Java source/target level is Java 8 (`sling.java.version=8`).
+- Parent POM is `org.apache.sling:sling-bundle-parent:66`.
+- Oak baseline is `1.44.0` (minimum required for
`JackrabbitNode.getPropertyOrNull` support).
+- `org.apache.sling.scripting.api` is optional at runtime
(`resolution:=optional` in `bnd.bnd`).
+- Bundle nodetypes are provided from `src/main/resources/SLING-INF/nodetypes/`.
