This is an automated email from the ASF dual-hosted git repository. rombert pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/sling-whiteboard.git
commit 63372cea4b6c3b00f908f1196235c0b20f536ebc Author: Robert Munteanu <[email protected]> AuthorDate: Fri Apr 17 17:16:19 2026 +0200 add skill for updating the parent pom --- skills/README.md | 17 ++++ skills/update-sling-parent-pom/SKILL.md | 60 ++++++++++++ .../reference/osgi-annotations.md | 109 +++++++++++++++++++++ .../update-sling-parent-pom/reference/osgi-r6.md | 4 + .../reference/rat-disable.md | 3 + .../reference/rat-enable.md | 1 + .../update-sling-parent-pom/reference/servlet-3.md | 3 + 7 files changed, 197 insertions(+) diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000..1e7fdd09 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,17 @@ +# Apache Sling Agent Skills + +A set of [Agent Skills](https://agentskills.io/) for Apache Sling developers and users. + +Current skills: + +- update-sling-parent-pom: Updates the parent POM of a Sling project to the next version. + +## Installation + +Using [npx skills](https://github.com/vercel-labs/skills): + +```bash + npx skills add apache/sling-whiteboard +``` + +Alternatively, clone the repository and copy the skill to a locations supported by your coding assitant. diff --git a/skills/update-sling-parent-pom/SKILL.md b/skills/update-sling-parent-pom/SKILL.md new file mode 100644 index 00000000..6017341b --- /dev/null +++ b/skills/update-sling-parent-pom/SKILL.md @@ -0,0 +1,60 @@ +--- +name: update-sling-parent-pom +description: Use when the user asks to upgrade the Sling parent POM version in their project +--- + +# Updating the Sling Parent POM + +## When to use + +Use when the user asks to upgrade the Sling parent POM version in their project. + +## Instructions + + +- run a full Maven build with the `clean verify`. Use the Java version required by the current parent pom version. If the build fails abort execution and inform the user of the root cause. Do not proceeed, otherwise it is impossible to validate the parent pom upgrade. +- check if any known issues with workarounds exist but to do not remove them +- identify the current version of the Sling parent POM in the user's project +- determine the next available version, typically incrementing by 1. For example, if the version is '22' the next version would be '23' +- update the parent pom version +- run a full Maven build with the `clean verify` goals using the Java version required by the new parent pom version. +- apply additional verification steps as needed if the specific version requires it +- if workarounds were present before updating the parent pom version, check if they can be removed. If they are needed add them back + +Do not touch the git repository state - no staging/unstaging, no commits, no pushes. + +### Java versions + +Different parent pom versions require different Java versions. This is listed in the table below. If building with a certain Java version is needed, use the following commands: + +- Java 8: `mvn8` +- Java 11: `mvn11` +- Java 17: `mvn17` +- Java 21: `mvn21` + +| Parent POM Version | Java Version(s) | Additional fixes needed | +|--------------------|-----------------|-------------------------| +| 22 | 8 | None | +| 23 | 8 | rat-disable | +| 24 | 8 | None | +| 25 | 8 | None | +| 26 | 8 | None | +| 27 | 8 | osgi-r6,servlet-3 | +| 28 | 8 | None | +| 29 | 8 | None | +| 30 | 8 | None | +| 31 | 8 | osgi-annotations | + + +### Additional fixes + +See the following reference files for additional fixes needed to update to a specific parent pom version. + +- rat-disable: [rat-disable.md](./reference/rat-disable.md) +- osgi-r6: [osgi-r6.md](./reference/osgi-r6.md) +- servlet-3: [servlet-3.md](./reference/servlet-3.md) +- osgi-annotations: [osgi-annotations.md](./reference/osgi-annotations.md) + +### Workarounds + +- rat-enable: [rat-enable.md](./reference/rat-enable.md) diff --git a/skills/update-sling-parent-pom/reference/osgi-annotations.md b/skills/update-sling-parent-pom/reference/osgi-annotations.md new file mode 100644 index 00000000..ffbae0de --- /dev/null +++ b/skills/update-sling-parent-pom/reference/osgi-annotations.md @@ -0,0 +1,109 @@ +# OSGi Annotations + +Replace usage of the deprecated Apache Felix SCR annotations with the official OSGi annotations. + +## pom.xml + +Remove the following plugins: +- org.apache.felix:maven-scr-plugin + +Remove the following dependencies: +- org.apache.felix:org.apache.felix.scr.annotations + + +## Java imports + +Imports to remove + +```java +import org.apache.felix.scr.annotations.Activate; +import org.apache.felix.scr.annotations.Component; +import org.apache.felix.scr.annotations.Deactivate; +import org.apache.felix.scr.annotations.Property; +import org.apache.felix.scr.annotations.PropertyUnbounded; +import org.apache.felix.scr.annotations.Reference; +import org.apache.felix.scr.annotations.ReferenceCardinality; +import org.apache.felix.scr.annotations.ReferencePolicy; +import org.apache.felix.scr.annotations.Service; +``` + +Imports to add + +```java +import org.osgi.service.component.annotations.Activate; +import org.osgi.service.component.annotations.Component; +import org.osgi.service.component.annotations.Deactivate; +import org.osgi.service.component.annotations.Reference; +import org.osgi.service.component.annotations.ReferenceCardinality; +import org.osgi.service.component.annotations.ReferencePolicy; +import org.osgi.service.metatype.annotations.AttributeDefinition; +import org.osgi.service.metatype.annotations.Designate; +import org.osgi.service.metatype.annotations.ObjectClassDefinition; +``` + +## The @Service annotation + +The `@Service` annotation is no longer needed. Instead, the `service` attribute of the `@Component` annotation should be used to specify the service interfaces. + +Before: + +``java +@Component +@Service(MyService.class) +``` + +After + +```java +@Component(service = MyService.class) +``` + +## The @Property annotation for a top-level class + +The `@Property` annotation is replaced by the 'property' attribute of the `@Component` annotation. + +Before: + +```java +@Component +@Property(name = Constants.SERVICE_DESCRIPTION, value = "Apache Sling MIME Type Service") +``` + +After: + +```java +@Component + property = { + Constants.SERVICE_DESCRIPTION + "=Apache Sling MIME Type Service" + }) +``` + +## The @Properties annotation + +The `@Properties` annotation is replaced by the 'property' attribute of the `@Component` annotation. + +Before: +```java +@Component +@Properties({ + @Property(name = "sling.servlet.extensions", value = "json"), + @Property(name = "sling.servlet.resourceTypes", value = "sling/bar") +}) +``` + +After: +```java +@Component( + property = { + "sling.servlet.extensions=json", + "sling.servlet.resourceTypes=sling/bar" + } +) +``` + +## The ReferenceCardinality enum + +The enum values have changed: + +- OPTIONAL_UNARY → OPTIONAL +- OPTIONAL_MULTIPLE → MULTIPLE diff --git a/skills/update-sling-parent-pom/reference/osgi-r6.md b/skills/update-sling-parent-pom/reference/osgi-r6.md new file mode 100644 index 00000000..3df6be1a --- /dev/null +++ b/skills/update-sling-parent-pom/reference/osgi-r6.md @@ -0,0 +1,4 @@ +Replace the following Maven dependencies + +- org.osgi:org.osgi.core → org.osgi:osgi.core +- org.osgi:org.osgi.compendium → org.osgi:osgi.cmpn diff --git a/skills/update-sling-parent-pom/reference/rat-disable.md b/skills/update-sling-parent-pom/reference/rat-disable.md new file mode 100644 index 00000000..6b0e7022 --- /dev/null +++ b/skills/update-sling-parent-pom/reference/rat-disable.md @@ -0,0 +1,3 @@ +The RAT profile was enabled by default with SLING-4511. If this causes failures right after upgrade, you can temporarily disable by running Maven with '-Drat.skip=true'. + +If this succeeds, ask the user if the property should be added to the pom.xml to permanently skip the check. diff --git a/skills/update-sling-parent-pom/reference/rat-enable.md b/skills/update-sling-parent-pom/reference/rat-enable.md new file mode 100644 index 00000000..9ba6d59a --- /dev/null +++ b/skills/update-sling-parent-pom/reference/rat-enable.md @@ -0,0 +1 @@ +If the rat.disable property is set to true in the parent pom, run a Maven build with `-Drat.disable=false`. If the build succeeds, ask the user if the property should be removed from the parent pom. diff --git a/skills/update-sling-parent-pom/reference/servlet-3.md b/skills/update-sling-parent-pom/reference/servlet-3.md new file mode 100644 index 00000000..e40b0dc6 --- /dev/null +++ b/skills/update-sling-parent-pom/reference/servlet-3.md @@ -0,0 +1,3 @@ +Replace the following Maven dependencies: + +- javax.servlet:servlet-api → javax.servlet:javax.servlet-api
