# CXF Release to JBoss Nexus 3

## Overview

This document describes the process for releasing an Apache CXF internal fork to the JBoss Nexus 3 Maven repository. The release is built from a `jboss-<major>.SP` branch (e.g. `jboss-4.1.8.SP`, `jboss-3.5.11.SP`) that contains JBoss-specific customizations (reverts, Nexus 3 deployment config) on top of the upstream CXF release branch.

The process has been used for two release lines with different JDK requirements:

| Release line | Build JDK | Deploy JDK | Deploy approach |
|---|---|---|---|
| **4.1.x** (e.g. `4.1.8-jbossorg-1`) | JDK 17+ | JDK 17+ | Single `mvn clean deploy` |
| **3.5.x** (e.g. `3.5.11-jbossorg-3`) | JDK 8 | JDK 17 | Split: `mvn install` (JDK 8) then `mvn deploy` (JDK 17, no recompile) |

The split is needed for 3.5.x because the `nxrm3-maven-plugin:1.0.13` requires JDK 17 (class file version 61.0), while CXF 3.5.x must be compiled with JDK 8.

## Prerequisites

- Local CXF clone with the SP branch checked out
- GPG key configured for artifact signing (`gpg.pinEntryMode=loopback`)
- Nexus credentials in `~/.m2/settings.xml` with server ID `jboss`
- `jq` and `curl` installed (for cleanup/listing scripts)
- For 3.5.x: both JDK 8 and JDK 17 available (e.g. via SDKMAN)

## Branch Structure

The `jboss-<major>.SP` branch sits on top of the upstream CXF release branch with these additions:

1. **Reverts** — any upstream commits that need to be backed out for JBoss compatibility
2. **JBoss Nexus Deployment commit** — adds to the root `pom.xml`:
   - `jboss-release` profile with `nxrm3-maven-plugin` staging-deploy, GPG signing, and disabled default deploy plugin
   - Plugin management for `maven-gpg-plugin`, `wildfly-maven-gpg-plugin`, and `nxrm3-maven-plugin`
   - Properties: `nexus.serverId`, `nexus.repository.release` (`jbossws`), `nexus.repository.staging` (`jboss-io`), `nexus.repository.url`, `nexus.staging.tag`

## Release Steps

### 1. Set the release version

From the SP branch:

```bash
mvn versions:set -DnewVersion=<version> -DgenerateBackupPoms=false
```

Example: `mvn versions:set -DnewVersion=4.1.8-jbossorg-1 -DgenerateBackupPoms=false`

### 2. Commit and tag

```bash
find . -name 'pom.xml' -not -path '*/target/*' -exec git add {} +
git commit -m "Prepare release cxf-<version>"
git tag cxf-<version>
git checkout cxf-<version>
```

### 3. Deploy to staging

#### 4.1.x (single JDK)

```bash
mvn clean deploy -Pjboss-release,deploy -DskipTests -Dcyclonedx.skip=true
```

#### 3.5.x (split JDK build/deploy)

**Step 1 — Build and install with JDK 8:**

```bash
mvn clean install -Pdeploy -DskipTests -Dcyclonedx.skip=true -Dmaven.javadoc.failOnError=false
```

**Step 2 — Switch to JDK 17, then deploy (no `clean`, no recompile):**

```bash
mvn deploy -Pjboss-release,deploy -DskipTests -Dcyclonedx.skip=true \
  -Dmaven.main.skip=true -Dmaven.resources.skip=true \
  -Dmaven.test.skip=true -Dmaven.test.skip.exec=true \
  -Dmaven.javadoc.failOnError=false
```

The extra flags for 3.5.x:
- **`-Dmaven.main.skip=true`** — skips recompilation so the JDK 8-built classes in `target/` are preserved
- **`-Dmaven.resources.skip=true`** — skips resource processing
- **`-Dmaven.test.skip=true`** — skips test compilation and execution
- **`-Dmaven.test.skip.exec=true`** — skips `maven-invoker-plugin` integration tests (used by `cxf-java2wadl-plugin`, bound to `skipInvocation` property)
- **`-Dmaven.javadoc.failOnError=false`** — `com.sun.javadoc` API was removed in JDK 17, so javadoc generation fails for modules that use it (e.g. `cxf-java2wadl-plugin`); this flag lets the build continue

Key profiles (both variants):
- **`jboss-release`** — activates nxrm3 staging-deploy to `jboss-io` repo with tag `cxf-<version>`, plus GPG signing
- **`deploy`** — activates `maven-source-plugin` (attaches `-sources.jar`), `maven-javadoc-plugin` (attaches `-javadoc.jar`), `cyclonedx-maven-plugin` (SBOM), and includes the `distribution` module

Both profiles are required. Without `-Pdeploy`, source and javadoc jars are not generated.

### 4. Verify staged content

Use the `nexus-cleanup.sh` script in list mode to verify what was staged:

```bash
./nexus-cleanup.sh --list jboss-io cxf-<version>
```

Redirect output for comparison:

```bash
./nexus-cleanup.sh --list jboss-io cxf-<version> | tee staged.txt
```

### 5. Validate against Maven Central

Compare the staged components against what Apache CXF deploys for the corresponding upstream version. The reference list is in `cxf-4.1.7-maven-central-components.txt` (191 components across multiple group IDs).

The expected component count should match the Maven Central reference. Use the Python comparison script:

```python
staged = set()
with open('staged.txt') as f:
    for line in f:
        line = line.strip()
        if line.startswith('org.apache.cxf'):
            parts = line.split(':')
            staged.add(f'{parts[0]}:{parts[1]}')

central = set()
with open('cxf-4.1.7-maven-central-components.txt') as f:
    for line in f:
        line = line.strip()
        if line:
            central.add(line)

print(f'Staged: {len(staged)}, Central: {len(central)}, Match: {len(staged & central)}')
print('Extra:', sorted(staged - central))
print('Missing:', sorted(central - staged))
```

### 6. Run Nexus validation job

Trigger the JBoss Nexus 3 validation job and review the report. If validation passes, promote from staging (`jboss-io`) to release (`jbossws`).

### 7. Reset branch for next development

```bash
git checkout jboss-4.1.x.SP
mvn versions:set -DnewVersion=<next-SNAPSHOT> -DgenerateBackupPoms=false
```

## Cleanup / Retry

If a staging deployment needs to be cleaned up (e.g., validation failures, partial uploads), there are two options:

### Option A: nxrm3 maven plugin `staging-delete`

```bash
mvn org.sonatype.plugins:nxrm3-maven-plugin:1.0.13:staging-delete -Pjboss-release
```

This uses the same credentials and config already in the POM. Requires JDK 17.

### Option B: `nexus-cleanup.sh` script

```bash
# List what's in the staging repo
./nexus-cleanup.sh --list <repository> <tag>

# Delete all staged content for a tag
./nexus-cleanup.sh <repository> <tag>
```

The script handles:
- **Pagination** — follows `continuationToken` to process all pages
- **Asset-level fallback** — if component-level delete fails (non-204), falls back to deleting individual assets

Usage: `./nexus-cleanup.sh [-l|--list] <repository> <tag>`

Note: the script prompts for Nexus credentials interactively and may leave behind a small number of components that fail to delete. The nxrm3 plugin approach (Option A) is generally cleaner.

### Recovering from a failed deployment

1. Clean up the staging repo: `./nexus-cleanup.sh jboss-io cxf-<version>`
2. Verify cleanup: `./nexus-cleanup.sh --list jboss-io cxf-<version>` (should show 0 components)
3. If re-tagging is needed:
   - `git tag -d cxf-<version>` (delete old tag)
   - `git checkout jboss-4.1.x.SP` (return to branch)
   - `git reset --hard <commit>` (reset to desired state)
   - Make fixes, re-commit, re-tag, re-deploy

## Key Findings

### Component coverage

Apache CXF 4.1.7 deploys **191 components** across these group IDs:

| Group ID | Example components |
|---|---|
| `org.apache.cxf` | Core, RT modules, tools, integration, spring-boot, testutils |
| `org.apache.cxf.archetype` | cxf-jaxrs-service, cxf-jaxws-javafirst, cxf-jaxws-wsdlfirst |
| `org.apache.cxf.services` | cxf-services (aggregator) |
| `org.apache.cxf.services.sts` | STS core, systests aggregator |
| `org.apache.cxf.services.sts.systests` | STS systests (basic, advanced, osgi) |
| `org.apache.cxf.services.ws-discovery` | WS-Discovery API, service |
| `org.apache.cxf.services.wsn` | WSN API, core, osgi |
| `org.apache.cxf.services.xkms` | XKMS client, common, service, war, x509-handlers, x509-repo-ldap |
| `org.apache.cxf.systests` | All system test modules |
| `org.apache.cxf.systests.wsdl_maven` | cxf-systests-codegen, cxf-systests-java2ws |

All of these are included in a full `mvn deploy -Pdeploy` — no `-pl` exclusions needed.

### Javadoc artifacts

Not all modules produce javadoc jars — even on Maven Central. POM-only modules (parent, bom, aggregators), some test modules, war modules, and archetypes do not have `-javadoc.jar`. This is expected and accepted by Maven Central validation. JBoss Nexus 3 validation may have stricter rules — check the validation report.

### Profile dependencies

- `-Pdeploy` adds: `maven-source-plugin`, `maven-javadoc-plugin`, `cyclonedx-maven-plugin`, and the `distribution` module
- `-Pjboss-release` adds: `nxrm3-maven-plugin` staging-deploy, `maven-gpg-plugin` signing, disables default `maven-deploy-plugin`
- Both are required for a correct deployment

### CycloneDX

CycloneDX SBOM generation can be skipped with `-Dcyclonedx.skip=true` if not required for the JBoss release.

## Files

| File | Purpose |
|---|---|
| `nexus-cleanup.sh` | List/delete staged content in Nexus 3 by repository and tag |
| `cxf-4.1.7-maven-central-components.txt` | Reference: 191 components deployed by Apache CXF 4.1.7 |
| `jboss-nexus-deploy-additions.txt` | Reference: POM changes for JBoss Nexus 3 deployment |
