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-servlets-post.git
The following commit(s) were added to refs/heads/master by this push:
new f7f2681 docs: add AGENTS.md, CLAUDE.md, and expand README (#36)
f7f2681 is described below
commit f7f26817766a1c1d9dc21af59a1699ec1fc91f4c
Author: Carsten Ziegeler <[email protected]>
AuthorDate: Tue Jun 2 07:31:05 2026 +0200
docs: add AGENTS.md, CLAUDE.md, and expand README (#36)
Add AI agent instructions (AGENTS.md) and a CLAUDE.md pointer file.
Expand README with overview, extension points, build commands, manual
smoke-test instructions, and repository layout.
Co-authored-by: Maia <maia@noreply>
---
AGENTS.md | 72 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
CLAUDE.md | 1 +
README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
3 files changed, 142 insertions(+), 1 deletion(-)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..82abeac
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,72 @@
+# Project Overview
+
+Apache Sling Servlets POST (`org.apache.sling.servlets.post`) is an OSGi
bundle that provides the default POST servlet (`SlingPostServlet`) for Apache
Sling. It handles content creation, modification, deletion, copy, move, import,
and file upload operations against the Sling resource tree (typically backed by
JCR). The bundle exposes extension points via `JakartaPostOperation`,
`SlingJakartaPostProcessor`, `JakartaNodeNameGenerator`, and
`JakartaPostResponseCreator` OSGi services. It sup [...]
+
+# Core Commands
+
+- **Build:** `mvn clean install`
+- **Build (skip tests):** `mvn clean install -DskipTests`
+- **Unit tests only:** `mvn test`
+- **Integration tests:** `mvn verify` (runs `ModifyOperationIT` via
maven-failsafe-plugin)
+- **Single test class:** `mvn test -Dtest=HtmlResponseTest`
+- **Single IT class:** `mvn verify -Dit.test=ModifyOperationIT`
+- **Check OSGi bundle headers:** inspect
`target/org.apache.sling.servlets.post-*.jar` — metadata generated by
`bnd-maven-plugin` from `bnd.bnd`
+- **Manual file-upload smoke tests against a running Sling instance:** `sh
developer-tests/testFileUploads.sh <testfile>` (expects Sling on
`localhost:8080` as `admin:admin`)
+
+# Project Layout
+
+```
+pom.xml Maven build descriptor; packaging = jar (OSGi
bundle via bnd)
+bnd.bnd OSGi bundle manifest overrides and bnd
instructions
+src/
+ main/java/org/apache/sling/servlets/post/
+ *.java Public API: interfaces & abstract classes
(PostOperation, PostResponse, etc.)
+ exceptions/ PreconditionViolatedPersistenceException,
TemporaryPersistenceException
+ impl/
+ SlingPostServlet.java Core servlet; dispatches to PostOperation
implementations
+ operations/ Built-in operations: Modify, Delete, Copy,
Move, Import, Checkin/out, etc.
+ helper/ Internal helpers: file upload, property value
handling, node naming, chunked upload
+ wrapper/ Jakarta↔javax bridging adapters for legacy SPI
consumers
+ main/resources/
+ SLING-INF/nodetypes/chunk.cnd JCR node type for chunked upload nodes
+ org/apache/sling/servlets/post/ HTML response templates
+ system/sling.js Bundled JS resource
+ test/java/ JUnit 4 unit tests and one Failsafe IT
(ModifyOperationIT)
+developer-tests/ Shell scripts for manual smoke-testing against
a live Sling instance
+```
+
+# Development Patterns & Constraints
+
+- **Java version:** 17 (`sling.java.version` property).
+- **OSGi:** Use `org.osgi.service.component.annotations` (`@Component`,
`@Reference`, etc.). No Felix SCR annotations.
+- **Jakarta-first:** New code must use `jakarta.servlet` and Sling Jakarta
APIs (`SlingJakartaHttpServletRequest`, etc.). Legacy `javax.servlet` support
is bridged in `impl/wrapper` only.
+- **Coding style:** 4-space indentation, no tabs. Follow existing Apache Sling
conventions. License headers required on all source files (enforced by
`apache-rat-plugin`).
+- **No public API in `impl`:** Classes under `impl` are internal; Javadoc is
excluded for that package. All public SPI lives in
`org.apache.sling.servlets.post` (top-level).
+- **OSGi versioning:** Bundle API is baselined by `bnd-baseline-maven-plugin`
— semantic versioning must be maintained. Changing a public interface requires
a minor or major version bump.
+- **Shading:** `maven-shade-plugin` inlines selected classes from
`jackrabbit-jcr-commons` and `sling-jcr-contentparser` (relocated under
`impl.*` packages) to avoid runtime dependency conflicts.
+- **Dynamic imports:** JCR packages and `sling.jcr.contentloader` are
`resolution:=dynamic` in `bnd.bnd`; the bundle works without JCR at runtime.
+
+# Git Workflow
+
+- Single `master` branch; releases tagged as
`org.apache.sling.servlets.post-<version>`.
+- Commit messages reference JIRA issues: `SLING-XXXXX Description (#PR)`.
+- PRs target `master`. CI runs via the `Jenkinsfile` (ASF Jenkins).
+- No force-pushes to `master`. Do not `git push` from agent environments.
+
+# Testing Guidelines
+
+- **Framework:** JUnit 4 + Mockito. Integration tests use Sling Mock Oak
(`sling-mock-oak`).
+- **Unit tests:** `src/test/java/**/*Test.java` — picked up by
`maven-surefire-plugin`.
+- **Integration tests:** `src/test/java/**/*IT.java` — picked up by
`maven-failsafe-plugin`; run only during `verify` phase.
+- **Test placement:** Mirror the main source package structure under
`src/test/java`.
+- **Coverage:** No coverage gate configured; rely on code review.
+- **Sling Mock:** Use `org.apache.sling.testing.sling-mock.junit4` for tests
needing a resource resolver. See existing `*IT.java` for setup patterns.
+
+# Gotchas
+
+- **Two parallel API families:** The public package has both
`PostOperation`/`PostResponse` (javax-based, deprecated) and
`JakartaPostOperation`/`JakartaPostResponse` (Jakarta-based). Always extend or
implement the Jakarta variants for new work.
+- **`bnd-baseline` will fail** if you change a public method signature without
bumping the package version in `package-info.java`.
+- **Shaded classes:** `org.apache.jackrabbit.util.ISO8601`, `Text`, and
`JsonTicksConverter` are embedded and relocated. Do not add direct compile-time
imports of those originals in non-impl code.
+- **`ModifyOperationIT`** requires Oak on the classpath; failsafe excludes the
older `jackrabbit-api` jar and substitutes `oak-jackrabbit-api` — if you add
JCR dependencies, verify classpath ordering in the failsafe config.
+- **File upload chunking:** The chunked upload protocol uses custom JCR node
types defined in `chunk.cnd`. Changes to chunk handling must account for the
`ChunkCleanUpTask` scheduled cleanup.
+- **`:redirect` URI validation:** `SlingPostServlet` validates redirect URIs
against the request host to prevent open-redirect. Tests must provide a proper
`Host` header or mock the URI check.
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 5704d9b..01f233c 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,74 @@
# Apache Sling Default POST Servlets
-Provides default POST servlets.
+Provides default POST servlets for Apache Sling.
This module is part of the [Apache Sling](https://sling.apache.org) project.
You can read more about this module on our [documentation
site](https://sling.apache.org/documentation/bundles/manipulating-content-the-slingpostservlet-servlets-post.html).
+
+## Overview
+
+The bundle provides the default `SlingPostServlet` and built-in POST
operations for Sling content changes, including:
+
+- create and modify
+- delete
+- copy and move
+- import
+- checkin/checkout and versioning helpers
+- file upload (regular, streamed, and chunked)
+
+The implementation is **Jakarta Servlet-first** and uses Sling Jakarta APIs.
Legacy `javax.servlet` integration remains available through wrapper adapters
under `impl/wrapper`.
+
+## Extension points
+
+Custom behavior can be provided via OSGi services such as:
+
+- `JakartaPostOperation`
+- `SlingJakartaPostProcessor`
+- `JakartaNodeNameGenerator`
+- `JakartaPostResponseCreator`
+
+## Build and test
+
+Java 17 is required.
+
+- Full build: `mvn clean install`
+- Build without tests: `mvn clean install -DskipTests`
+- Unit tests: `mvn test`
+- Integration tests (Failsafe, including `ModifyOperationIT`): `mvn verify`
+- Single unit test class: `mvn test -Dtest=HtmlResponseTest`
+- Single integration test class: `mvn verify -Dit.test=ModifyOperationIT`
+
+## Manual upload smoke tests
+
+For manual file-upload protocol checks against a running Sling instance on
`localhost:8080` (`admin:admin`), use:
+
+`sh developer-tests/testFileUploads.sh <testfile>`
+
+See `developer-tests/README.md` and `Protocols.md` for protocol and script
details.
+
+## Repository layout
+
+```text
+pom.xml Maven build descriptor (packaging: jar)
+bnd.bnd OSGi bundle instructions and embedded resources
+src/
+ main/java/org/apache/sling/servlets/post/
+ *.java Public API and SPI
+ exceptions/ Persistence-related exceptions
+ impl/ Internal servlet and operation implementation
+ operations/ Built-in POST operations
+ helper/ Internal helpers (upload, property handling,
naming)
+ wrapper/ Jakarta <-> javax bridging adapters
+ main/resources/
+ SLING-INF/nodetypes/chunk.cnd Chunked upload node type definitions
+ org/apache/sling/servlets/post/ HTML response templates
+ system/sling.js Bundled JS resource
+ test/java/ Unit and integration tests
+developer-tests/ Manual developer test scripts
+```
+
+## Notes
+
+- OSGi metadata is generated with bnd (`bnd-maven-plugin`), with API baseline
checks via `bnd-baseline-maven-plugin`.
+- The build shades selected classes from `jackrabbit-jcr-commons` and
`sling-jcr-contentparser` into internal `impl` packages.
+- JCR and `org.apache.sling.jcr.contentloader` imports are configured as
dynamic for runtime flexibility.
