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-jackrabbit-base.git
The following commit(s) were added to refs/heads/master by this push:
new c7ddaa3 docs: update AGENTS.md and README.md with clarifications and
new commands (#5)
c7ddaa3 is described below
commit c7ddaa3326b9339365e41fdc941dd2b2c80c3763
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Thu Jul 16 17:58:23 2026 +0200
docs: update AGENTS.md and README.md with clarifications and new commands
(#5)
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 37 ++++++++++++++++++++-----------------
README.md | 12 ++++++++++++
2 files changed, 32 insertions(+), 17 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
index 8bab4d6..7198f69 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
# Project Overview
-`org.apache.sling.jcr.jackrabbit.base` is an OSGi bundle providing Jackrabbit
utility classes for Apache Sling. It bridges Jackrabbit's internal
configuration and security APIs with the OSGi service registry. Key components:
`OsgiBeanFactory` (OSGi-aware Jackrabbit bean factory), `DelegatingLoginModule`
(JAAS login delegation), `DelegatingPrincipalProviderRegistry`,
`MultiplexingAuthorizableAction`, and `PrincipalProviderTracker`. No web layer
— pure OSGi/JCR integration library.
+`org.apache.sling.jcr.jackrabbit.base` is an OSGi bundle providing Jackrabbit
utility classes for Apache Sling. It bridges Jackrabbit configuration and
security extension points with the OSGi service registry. Key components:
`OsgiBeanFactory` (OSGi-aware Jackrabbit bean factory), `DelegatingLoginModule`
(JAAS login delegation), `DelegatingPrincipalProviderRegistry`,
`MultiplexingAuthorizableAction`, and `PrincipalProviderTracker`. No web layer
— pure OSGi/JCR integration library.
# Core Commands
@@ -11,7 +11,7 @@ mvn clean install
# Compile only
mvn compile
-# Run full test suite
+# Run tests
mvn test
# Run a single test class
@@ -26,22 +26,25 @@ mvn spotless:apply
# Check formatting without modifying
mvn spotless:check
-# Verify OSGi baseline compliance
+# Full verification (includes parent build checks)
mvn verify
+
+# License header compliance
+mvn apache-rat:check
```
# Project Layout
-```
+```text
pom.xml # Maven build descriptor; inherits
sling-bundle-parent:66
src/
main/
java/
org/apache/sling/jcr/jackrabbit/base/
config/
- OsgiBeanFactory.java # OSGi-aware BeanFactory for Jackrabbit
repository config
+ OsgiBeanFactory.java # OSGi-aware BeanFactory for
repository config
security/
- DelegatingLoginModule.java # Delegates JAAS login to
OSGi-registered modules
+ DelegatingLoginModule.java # Delegates JAAS login to
OSGi or Jackrabbit fallback
DelegatingPrincipalProviderRegistry.java
MultiplexingAuthorizableAction.java # Fans out authorizable
actions to OSGi services
PrincipalProviderTracker.java # Tracks OSGi principal
provider services
@@ -49,32 +52,33 @@ src/
target/ # Build output; not committed
```
-No `src/test/` directory — currently no tests.
+No `src/test/` directory currently exists.
# Development Patterns & Constraints
- **Java version**: Java 8 source compatibility (`sling.java.version=8`). Do
not use Java 9+ APIs.
-- **Code style**: Google Java Format (enforced by Spotless, inherited from
`sling-bundle-parent`). Run `mvn spotless:apply` before committing.
+- **Code style**: Google Java Format (enforced by Spotless via the parent
POM). Run `mvn spotless:apply` before committing.
- **Indentation**: 2 spaces (Google style).
-- **OSGi**: OSGi R6/R7 annotations (`org.osgi.service.component.annotations`).
Do not use Felix SCR annotations.
+- **OSGi integration style**: This module uses
`BundleContext`/`ServiceTracker` APIs directly for service tracking and
registration (not Declarative Services components).
- **Imports**: No wildcard imports. Static imports only for
constants/utilities where idiomatic.
-- **Logging**: SLF4J only (`org.slf4j.Logger`/`LoggerFactory`). No
`java.util.logging` or Log4j direct usage.
+- **Logging**: SLF4J only (`org.slf4j.Logger`/`LoggerFactory`).
- **License headers**: Every `.java` file must carry the Apache 2.0 license
header. RAT check (`mvn apache-rat:check`) enforces this.
-- **Dependencies**: All dependencies declared `provided` (OSGi container
supplies them at runtime) or `test`. Do not add `compile`-scope runtime deps
without discussion.
-- **Animal Sniffer**: `animal-sniffer-maven-plugin` checks Java 8 API
compliance on every build.
+- **Dependencies**: Runtime dependencies are `provided` (container-supplied);
test-only dependencies use `test` scope.
+- **Animal Sniffer**: `animal-sniffer-maven-plugin` enforces Java 8 API
compatibility.
- **OSGi versioning**: Use `@org.osgi.annotation.versioning` on exported
packages (`package-info.java`).
# Git Workflow
- Mirrors Apache Sling conventions:
[https://sling.apache.org/contributing.html](https://sling.apache.org/contributing.html)
- Main branch: `master`
-- Commit messages: start with a short imperative summary (≤72 chars),
reference Jira issue where applicable (e.g., `SLING-12345 Fix
DelegatingLoginModule NPE`).
+- Commit messages: short imperative summary (≤72 chars), reference Jira issue
where applicable (e.g., `SLING-12345 Fix DelegatingLoginModule NPE`).
- Contributions via GitHub PRs against this repo; CI runs via Jenkins
(`slingOsgiBundleBuild()` pipeline function).
- Do not push directly to `master` without review.
# Testing Guidelines
- Framework: JUnit 4 (`junit:junit`, test scope).
+- Test logging backend: `org.slf4j:slf4j-simple` (test scope).
- Test files go in `src/test/java/` mirroring the main package structure.
- Run all tests: `mvn test`
- Run one test: `mvn test -Dtest=ClassName` or `mvn test
-Dtest=ClassName#methodName`
@@ -85,14 +89,13 @@ No `src/test/` directory — currently no tests.
- **No OSGi runtime in tests**: There is no embedded OSGi framework for tests.
Mock `BundleContext` and related OSGi interfaces manually or with Mockito.
- **Jackrabbit 2.x, not Oak**: This bundle targets `jackrabbit-core:2.5.2`
(Jackrabbit 2, not Apache Jackrabbit Oak). APIs differ substantially from Oak.
-- **Spotless fail on CI**: Formatting is checked during `verify`. Always run
`mvn spotless:apply` before pushing — raw format mismatches will break the
Jenkins build.
+- **Spotless fail on CI**: Formatting is checked during `verify`. Always run
`mvn spotless:apply` before pushing.
- **RAT check**: Missing or malformed license headers fail the build. Any new
file needs the ASF license block.
-- **`bnd.baseline.fail.on.missing=false`**: OSGi semantic versioning baseline
check is relaxed (no baseline artifact yet). Enable carefully when releasing.
-- **Animal Sniffer**: Importing any API added after Java 8 (e.g.,
`java.util.Optional.ifPresentOrElse`) will fail the build silently at the
sniffer phase — check carefully when upgrading utilities.
+- **`bnd.baseline.fail.on.missing=false`**: OSGi semantic versioning baseline
checking is relaxed when a baseline artifact is missing.
+- **Animal Sniffer**: Importing any API added after Java 8 (for example
`java.util.Optional.ifPresentOrElse`) fails the build in the sniffer phase.
# Security
<!-- sling-security-default:start -->
The threat model for this project is
https://github.com/apache/sling/blob/master/docs/threat-model.md .
<!-- sling-security-default:end -->
-
diff --git a/README.md b/README.md
index 67e2fb1..5448fec 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,9 @@ mvn compile
# Run tests
mvn test
+# Build without tests
+mvn install -DskipTests
+
# Check formatting
mvn spotless:check
@@ -45,17 +48,23 @@ mvn spotless:apply
# Full verification (includes integration checks from parent build)
mvn verify
+
+# License header compliance
+mvn apache-rat:check
```
## Requirements and Dependencies
* Java 8 (`sling.java.version=8`)
+* Maven build parent: `org.apache.sling:sling-bundle-parent:66`
* Apache Jackrabbit Core `2.5.2` (provided)
* JCR API (`javax.jcr:jcr`, provided)
* OSGi APIs (`org.osgi.framework`, `org.osgi.util.tracker`,
`org.osgi.annotation.versioning`, provided)
* SLF4J API (provided)
* JUnit 4 and `slf4j-simple` for tests
+* Animal Sniffer Maven Plugin
(`org.codehaus.mojo:animal-sniffer-maven-plugin:1.24`)
+ enforces Java 8 API compatibility
## Source Layout
@@ -68,4 +77,7 @@ src/main/java/org/apache/sling/jcr/jackrabbit/base/
DelegatingPrincipalProviderRegistry.java
MultiplexingAuthorizableAction.java
PrincipalProviderTracker.java
+ package-info.java
```
+
+There is currently no `src/test/java/` tree in this module.
