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-base.git
The following commit(s) were added to refs/heads/master by this push:
new 8596f52 docs: add AGENTS.md, CLAUDE.md, and expand README (#17)
8596f52 is described below
commit 8596f52f2f5c6e4585a884597c760b0742e1acbb
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 08:36:16 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#17)
Add AGENTS.md with full project overview, core commands, layout,
development constraints, testing guidelines, and gotchas. Add
CLAUDE.md that delegates to AGENTS.md. Expand README with build,
test, code quality, requirements, main components, project structure,
login administrative allow-list, and node-types/namespaces sections.
Also fix a minor typo ('can registered' → 'can be registered').
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 69 ++++++++++++++++++++++++++++++++++++++++++--
3 files changed, 166 insertions(+), 2 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3e04374
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,98 @@
+# Project Overview
+
+`org.apache.sling.jcr.base` is an OSGi bundle that provides JCR foundation
classes for Apache Sling. It supplies abstract base classes for implementing
`SlingRepository` (`AbstractSlingRepository2`,
`AbstractSlingRepositoryManager`), a `loginAdministrative` allow-list enforced
via OSGi component configuration, JCR node-type loading utilities,
access-control helpers, and a proxy/mount layer that lets multiple JCR
repositories appear as one. All components use OSGi R6/R7 Declarative Servic
[...]
+
+# Core Commands
+
+```bash
+# Build (compile + package, skip tests)
+mvn clean package -DskipTests
+
+# Full build with tests
+mvn clean verify
+
+# Run all tests
+mvn test
+
+# Run a single test class
+mvn test -Dtest=LoginAdminAllowListTest
+
+# Run a single test method
+mvn test -Dtest=LoginAdminAllowListTest#testAllowList
+
+# Lint / code style (Spotless + RAT)
+mvn spotless:check
+mvn apache-rat:check
+
+# Apply Spotless auto-formatting
+mvn spotless:apply
+
+# Generate Javadoc
+mvn javadoc:javadoc
+```
+
+No dev server — this is a library bundle deployed into an OSGi container
(e.g., Apache Felix / Karaf).
+
+# Project Layout
+
+```
+pom.xml Maven build descriptor
+bnd.bnd OSGi bundle manifest overrides
+src/
+ main/java/org/apache/sling/jcr/base/
+ AbstractSlingRepository2.java Base SlingRepository implementation
+ AbstractSlingRepositoryManager.java Manages repository lifecycle +
allow-list
+ NodeTypeLoader.java Registers CND node-type definitions
+ package-info.java Package-level OSGi version annotation
+ internal/
+ LoginAdminAllowList.java Enforces loginAdministrative allow-list
+ LoginAdminAllowListConfiguration.java OSGi Metatype config interface
+ AllowListFragment.java Whiteboard fragment for allow-list
entries
+ LegacyFragment.java Compatibility shim for old allow-list
configs
+ RepositoryPrinter*.java Felix WebConsole status printer
+ loader/Loader.java Bootstraps node types from bundle
resources
+ mount/Proxy*.java Proxy wrappers for RepositoryMount SPI
+ spi/
+ RepositoryMount.java SPI: plug in an additional JCR
repository
+ util/
+ AccessControlUtil.java JCR/Jackrabbit ACL helpers
+ RepositoryAccessor.java Repository lookup (JNDI / RMI / OSGi)
+ test/java/… JUnit 4 tests mirroring the main package tree
+target/ Build output (gitignored)
+```
+
+# Development Patterns & Constraints
+
+- **Java 8** source/target (`sling.java.version=8` in pom.xml). Do not use
APIs above Java 8.
+- **OSGi DS annotations only**: use `org.osgi.service.component.annotations.*`
and `org.osgi.service.metatype.annotations.*`. No Felix SCR annotations.
+- **4-space indentation**, no tabs. Spotless (Eclipse formatter) enforces this
— run `mvn spotless:apply` after edits.
+- Internal implementation classes live under `*.internal.*` packages; these
are not exported and must not be referenced from outside.
+- Public API packages carry `@Version` annotations in `package-info.java` —
bump the version in that file and in `bnd.bnd` when changing API.
+- Logging via SLF4J only (`org.slf4j.Logger`); never use `java.util.logging`
or `System.out`.
+- All source files require the Apache License 2.0 header; RAT enforces this.
+- The `bnd.bnd` file declares `Import-Package` overrides (e.g., optional RMI
import). Keep it in sync when adding new optional dependencies.
+
+# Git Workflow
+
+- Default branch: `master`
+- Feature branches: `<JIRA-issue>/short-description` (e.g.,
`SLING-12345/fix-allowlist`)
+- Commit messages: start with the JIRA issue key — `SLING-XXXXX: <imperative
summary>`
+- PRs target `master`; CI (Jenkins via `Jenkinsfile`) must pass before merge
+- Do not push directly to `master`; use PRs
+
+# Testing Guidelines
+
+- Framework: **JUnit 4** with Mockito 5 and Sling OSGi Mock / Sling Mock / JCR
Mock
+- Test files mirror main sources under `src/test/java/…`
+- OSGi component tests use `OsgiContext` (from
`org.apache.sling.testing.osgi-mock.junit4`)
+- Run coverage: `mvn test jacoco:report` (JaCoCo is inherited from the Sling
bundle parent POM)
+- Coverage report appears in `target/site/jacoco/`
+
+# Gotchas
+
+- **`loginAdministrative` is off by default**: bundles must register an
`AllowListFragment` OSGi service to be permitted. Tests that call
`loginAdministrative` without wiring the allow-list will get an exception.
+- **OSGi mock version matters**: the tests use `osgi-mock.junit4` 3.x; mixing
with 2.x artefacts breaks context setup.
+- **RMI dependency is optional**: `jackrabbit-jcr-rmi` is `provided` scope and
the Import-Package is `resolution:=optional`. Do not make it mandatory.
+- **Baseline check**: the parent POM runs OSGi semantic-version baseline
against the previous release JAR. Adding API without bumping the package
version will fail the build.
+- **Spotless must pass before RAT**: run `mvn spotless:apply` before
committing; otherwise the RAT XML-header check may report false positives on
reformatted files.
+- The `internal` packages are deliberately excluded from Javadoc generation
(see `pom.xml` `maven-javadoc-plugin` config).
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 ec034f8..cd8b489 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,65 @@
This module is part of the [Apache Sling](https://sling.apache.org) project.
-The JCR base bundle provides JCR utility classes and support for repository
mounts.
+The JCR base bundle provides JCR utility classes, base implementations for
`SlingRepository`, login administrative allow-list enforcement, node type
loading helpers, and support for repository mounts.
+
+# Build
+
+```bash
+mvn clean package -DskipTests
+```
+
+# Test
+
+```bash
+mvn clean verify
+```
+
+```bash
+mvn test
+mvn test -Dtest=LoginAdminAllowListTest
+mvn test -Dtest=LoginAdminAllowListTest#testAllowList
+```
+
+# Code Quality
+
+```bash
+mvn spotless:check
+mvn apache-rat:check
+mvn spotless:apply
+```
+
+# Requirements
+
+* Java 8 source/target
+* OSGi Declarative Services (`org.osgi.service.component.annotations`)
+* Optional Jackrabbit RMI support via `jackrabbit-jcr-rmi` (provided scope)
+
+# Main Components
+
+* `AbstractSlingRepository2` and `AbstractSlingRepositoryManager` provide the
core Sling repository base implementation and lifecycle integration.
+* `LoginAdminAllowList`, `AllowListFragment`, and `LegacyFragment` enforce and
bridge `loginAdministrative` allow-list configuration.
+* `NodeTypeLoader` and `internal.loader.Loader` register CND node types and
JCR namespaces from bundle headers.
+* `org.apache.sling.jcr.base.spi.RepositoryMount` and the internal proxy
classes support JCR repository mounts.
+* `util.AccessControlUtil` and `util.RepositoryAccessor` provide reusable JCR
access-control and repository lookup utilities.
+
+# Project Structure
+
+* `src/main/java` - bundle implementation and SPI
+* `src/test/java` - JUnit 4 + Sling testing mocks
+* `pom.xml` - Maven build (Sling bundle parent)
+* `bnd.bnd` - OSGi manifest instructions
+
+# Login Administrative Allow List
+
+`loginAdministrative` is protected by an allow list and is disabled unless
both repository-manager settings and allow-list rules permit access.
+
+Current configuration uses allow-list naming:
+
+* Main PID: `org.apache.sling.jcr.base.LoginAdminAllowList`
+* Fragment factory PID:
`org.apache.sling.jcr.base.LoginAdminAllowList.fragment`
+
+Legacy whitelist PIDs and properties are still supported for backward
compatibility, but they are deprecated.
# Repository Mount
@@ -18,9 +76,16 @@ a resource provider.
To support legacy code, this bundle provides an SPI interface
*org.apache.sling.jcr.base.spi.RepositoryMount* which
extends *JackrabbitRepository* (and through this *javax.jcr.Repository*). A
service registered as *RepositoryMount* registers
itself with the service registration property
*RepositoryMount.MOUNT_POINTS_KEY* which is a String+ property containing
-the paths in the JCR tree where the mount takes over the control of the JCR
nodes. The *RepositoryMount* can registered
+the paths in the JCR tree where the mount takes over the control of the JCR
nodes. The *RepositoryMount* can be registered
at a single path or multiple.
As *RepositoryMount* extends *JackrabbitRepository* the implementation of a
mount needs to implement the whole JCR API.
This is a lot of work compared to a *ResourceProvider*, therefore a
*RepositoryMount* should only be used if legacy
code using JCR API needs to be supported.
+
+# Node Types and Namespaces
+
+When present, the following bundle manifest headers are processed to register
repository metadata:
+
+* `Sling-Nodetypes`
+* `Sling-Namespaces`
