thomasmueller commented on code in PR #2745:
URL: https://github.com/apache/jackrabbit-oak/pull/2745#discussion_r2877404444
##########
AGENTS.md:
##########
@@ -0,0 +1,236 @@
+# AGENTS.md - AI Agent Instructions for Apache Jackrabbit Oak
+
+## Project Overview
+
+Apache Jackrabbit Oak is a scalable, high-performance hierarchical content
repository
+implementing the JCR (Java Content Repository) specification. It is a
multi-module Maven
+project with ~47 modules written in Java 11.
+
+## General Guidelines
+
+- When working on a specific area, first read the area-specific documentation
before
+ making changes (see doc links in the module tables below)
+- New code must have high test coverage — all critical paths must be covered
by tests
+- Write self-descriptive, easy-to-read code. Avoid trivial comments. Only add
comments
+ where the logic is complex and not obvious from the code itself
+- Use feature toggles for non-trivial changes. If the change is a bug fix, the
toggle
+ should be enabled by default. If the change introduces a new feature, the
toggle should
+ be disabled by default
+
+## Build Commands
+
+```bash
+# Full build (skip tests for speed)
+mvn clean install -DskipTests
+
+# Fast build (no tests, no coverage)
+mvn clean install -Pfast
+
+# Build a single module
+mvn clean install -pl oak-core -DskipTests
+
+# Build a module and its dependencies
+mvn clean install -pl oak-core -am -DskipTests
+
+# Rebuild a module and all modules that depend on it (use after SPI/API
changes)
+mvn clean install -pl oak-store-spi -amd -DskipTests
+
+# Full build with tests
+mvn clean install
+
+# Build with integration tests
+mvn clean install -PintegrationTesting
+```
+
+## Test Commands
+
+```bash
+# Run tests for a single module
+mvn test -pl oak-core
+
+# Run a specific test class
+mvn test -pl oak-core -Dtest=TreeTest
+
+# Run a specific test method
+mvn test -pl oak-core -Dtest=TreeTest#testMethodName
+
+# Run integration tests for a module
+mvn verify -pl oak-store-document -PintegrationTesting
+
+# Run with code coverage
+mvn verify -pl oak-core -Pcoverage -Dskip.coverage=false
+```
+
+**Test framework:** JUnit 4 (4.13.1) with Mockito 5.x (loaded as Java agent).
+Some modules also use EasyMock. Do not introduce JUnit 5 unless explicitly
requested.
+
+**Test fixtures:** Tests may run against multiple backend fixtures:
`SEGMENT_TAR` (default),
+`DOCUMENT_NS` (MongoDB), `DOCUMENT_RDB`, `SEGMENT_AWS`, `SEGMENT_AZURE`.
+
+## Repository Structure
+
+**Note:** Individual submodules may have their own `AGENTS.md` file with
module-specific
+instructions. When working within a particular module, check for and read its
`AGENTS.md`
+before making changes.
+
+All modules grouped by area. The **Description** column provides additional
context
+for understanding each module's role.
+
+### API & Core
+
+| Module | Purpose | Description
|
+|--------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `oak-api` | Public Oak API | Defines `ContentRepository`, `ContentSession`,
`Root`, `Tree` and other core interfaces for accessing repository content. See:
`oak-api/README.md`, `oak-doc/src/site/markdown/oak_api/error_codes.md` |
+| `oak-core` | Core repository implementation | MVCC-based transactional
content model, node state management, commit handling, and internal kernel.
See: `oak-doc/src/site/markdown/archigreat l-model.md`
|
+| `oak-core-spi` | Core SPI interfaces | Service Provider Interfaces for
plugins and storage backends (NodeStore, Commit, etc.)
|
+| `oak-commons` | Shared utilities | Common utility classes used across all
Oak modules
|
+| `oak-jackrabbit-api` | Jackrabbit API extensions | Additional API beyond the
JCR spec (e.g., extended session, security). See:
`oak-jackrabbit-api/README.md`
|
+| `oak-jcr` | JCR API binding | Implementation of the javax.jcr (JCR 2.0)
specification on top of Oak's content model
|
+| `oak-parent` | Parent POM | Dependency management and shared plugin settings
|
+
+### Node Store (Persistence)
+
+| Module | Purpose | Description |
+|--------|---------|-------------|
+| `oak-store-spi` | Storage SPI | Interfaces and base classes for implementing
custom NodeStore backends. See:
`oak-doc/src/site/markdown/nodestore/overview.md` |
+| `oak-store-composite` | Composite NodeStore | Combines multiple NodeStores,
allowing different subtrees to be backed by different stores. See:
`oak-doc/src/site/markdown/nodestore/compositens.md` |
+| `oak-store-document` | Document NodeStore | Stores content as documents in
MongoDB or relational databases (RDB). Supports clustering, revision
management, and branch tracking. See:
`oak-doc/src/site/markdown/nodestore/documentmk.md`,
`oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md`,
`oak-doc/src/site/markdown/nodestore/document/rdb-document-store.md` |
+| `oak-segment-tar` | Segment/TarMK storage | Immutable segment-based storage
using TAR files. Includes online/offline compaction and generational garbage
collection. Default for single-instance deployments. See:
`oak-doc/src/site/markdown/nodestore/segment/overview.md`,
`oak-doc/src/site/markdown/nodestore/segmentmk.md`,
`oak-segment-tar/release-howto.md` |
+| `oak-segment-remote` | Remote segment base | Shared base for cloud segment
backends (AWS, Azure) |
+| `oak-segment-aws` | Segment on AWS S3 | Remote segment store backend storing
segments in Amazon S3 |
+| `oak-segment-azure` | Segment on Azure Blob | Remote segment store backend
storing segments in Microsoft Azure Blob Storage. Includes Azurite test support
|
+
+### Blob / Binary Storage
+
+| Module | Purpose | Description |
+|--------|---------|-------------|
+| `oak-blob` | Blob SPI & base | Core interfaces and base classes for
BlobStore (binary large object) implementations. See: `oak-blob/README.md`,
`oak-doc/src/site/markdown/plugins/blobstore.md` |
+| `oak-blob-cloud` | Cloud blob base | Common functionality for cloud-based
BlobStore providers |
+| `oak-blob-cloud-azure` | Azure BlobStore | AzureDataStore implementation
storing binaries in Azure Blob Storage with direct binary access. See:
`oak-doc/src/site/markdown/features/direct-binary-access.md` |
+| `oak-blob-plugins` | Blob plugins | Additional BlobStore implementations and
cloud integration plugins (S3, etc.) |
+
+### Query & Indexing
+
+| Module | Purpose | Description |
+|--------|---------|-------------|
+| `oak-query-spi` | Query index SPI | Interfaces for implementing custom query
index providers. See: `oak-doc/src/site/markdown/query/query-engine.md` |
+| `oak-search` | Search framework | Higher-level search abstraction and query
optimization shared by Lucene and Elastic backends. See:
`oak-doc/src/site/markdown/query/query.md`,
`oak-doc/src/site/markdown/query/indexing.md`,
`oak-doc/src/site/markdown/query/index-management.md` |
+| `oak-lucene` | Lucene indexing | Embedded Apache Lucene full-text and
property indexing with facets, suggestions, spellcheck, and excerpts. See:
`oak-doc/src/site/markdown/query/lucene.md`,
`oak-doc/src/site/markdown/query/property-index.md`,
`oak-doc/src/site/markdown/query/hybrid-index.md` |
+| `oak-search-elastic` | Elasticsearch indexing | Distributed full-text search
and indexing via external Elasticsearch cluster. See:
`oak-doc/src/site/markdown/query/elastic.md` |
+
+### Security
+
+| Module | Purpose | Description |
+|--------|---------|-------------|
+| `oak-security-spi` | Security SPI | Interfaces for authentication and
authorization provider plugins. See:
`oak-doc/src/site/markdown/security/overview.md`,
`oak-doc/src/site/markdown/security/introduction.md` |
+| `oak-auth-external` | External authentication | Framework for external
identity providers (SAML, OAuth, etc.) with user/group synchronization. See:
`oak-auth-external/README.md`,
`oak-doc/src/site/markdown/security/authentication/external/` |
+| `oak-auth-ldap` | LDAP authentication | LDAP/Active Directory identity
provider with user and group sync. See: `oak-auth-ldap/README.md`,
`oak-doc/src/site/markdown/security/authentication/ldap.md` |
+| `oak-authorization-cug` | Closed User Groups | CUG-based authorization
restricting read access to defined groups on subtrees. See:
`oak-doc/src/site/markdown/security/authorization/cug.md` |
+| `oak-authorization-principalbased` | Principal-based authz | Access control
evaluated by principal rather than by content path. See:
`oak-doc/src/site/markdown/security/authorization/principalbased.md` |
+
+### Tools & CLI
+
+| Module | Purpose | Description |
+|--------|---------|-------------|
+| `oak-run` | CLI toolbox | Runnable JAR with commands for backup, restore,
compaction, debug console, index management, migration, and more. See:
`oak-run/README.md`, `oak-doc/src/site/markdown/command_line.md`,
`oak-doc/src/site/markdown/features/oak-run-nodestore-connection-options.md` |
+| `oak-run-commons` | CLI shared code | Base classes shared by oak-run
commands |
+| `oak-run-elastic` | CLI Elastic tools | Elasticsearch-specific oak-run
commands |
+| `oak-upgrade` | Migration tools | Upgrades Jackrabbit 2.x repositories to
Oak, including node store migration between backends. See:
`oak-doc/src/site/markdown/migration.md` |
+| `oak-http` | HTTP binding | REST/HTTP server exposing Oak repository
operations remotely. See: `oak-http/README.md` |
+
+### Other Modules
+
+- **Benchmarks:** `oak-benchmarks`, `oak-benchmarks-lucene`,
`oak-benchmarks-elastic` — performance benchmarks. See:
`oak-benchmarks/README.md`
+- **Integration tests:** `oak-it`, `oak-it-osgi` — cross-module and OSGi
integration tests
+- **Examples / training:** `oak-exercise`, `oak-examples`, `oak-pojosr` —
learning resources and OSGi test registry
+- **Documentation:** `oak-doc` (build with `-Pdoc`) — site source at
`oak-doc/src/site/markdown/`
+
+## Feature Toggles
+
+Oak has a built-in feature toggle mechanism for safely rolling out new
behavior at runtime.
+Toggles are disabled by default and can be enabled without redeployment.
+
+**Core API** (in `oak-core-spi`):
+- `Feature` — wrapper for checking toggle state. Create with
`Feature.newFeature(name, whiteboard)`,
+ check with `feature.isEnabled()`, clean up with `feature.close()`.
+ See:
`oak-core-spi/src/main/java/org/apache/jackrabbit/oak/spi/toggle/Feature.java`
+- `FeatureToggle` — the underlying toggle registered on the OSGi Whiteboard.
State is managed
+ via `setEnabled(boolean)` using an `AtomicBoolean` (thread-safe).
+ See:
`oak-core-spi/src/main/java/org/apache/jackrabbit/oak/spi/toggle/FeatureToggle.java`
+
+**Naming convention:** toggle names follow the pattern `FT_OAK-<issue>` or
+`FT_<DESCRIPTION>_OAK-<issue>` (e.g., `FT_OAK-11949`,
`FT_CLASSIC_MOVE_OAK-10147`).
+
+**How it works:**
+1. A component creates a toggle: `Feature ft =
Feature.newFeature("FT_OAK-XXXXX", whiteboard)`
+2. The toggle is registered on the Whiteboard for runtime discovery
+3. Code checks the toggle: `if (feature != null && feature.isEnabled()) { ...
}`
+4. Admin tooling can discover and flip toggles via the Whiteboard at runtime
+
+**Examples in the codebase:**
+- Query engine toggles (`FT_OAK-11949`, `FT_OAK-12007`) registered in
`oak-core/.../Oak.java`
+- Document store toggles (throttling, full GC, embedded verification) in
+ `oak-store-document/.../DocumentNodeStoreBuilder.java`
+- Some features also support a system property fallback (e.g.,
`oak.classicMove`)
+
+## Code Conventions
+
+### Style
+- No wildcard imports (import each class individually)
+- Follow existing code style in the module you are modifying
+- OSGi bundle compliance is required - modules produce OSGi bundles
Review Comment:
```suggestion
- Follow existing code style in the module you are modifying
- OSGi bundle compliance is required - modules produce OSGi bundles
- Never use regular expression parsing and find / replace for JSON or XML
data
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
