Release 8.0.0: Java 8 / javax

.cursor/rules/common-library-project.mdc

@@ -0,0 +1,48 @@
+---
+description: common-library-java artifact repo layout, release lines, and build
+alwaysApply: true
+---
+
+# common-library-java
+
+Maven artifact **`au.gov.nehta:common-library`** - shared Java utility classes used by other ADHA/NEHTA libraries (CDA package operations, argument validation, web-service helpers).
+
+## Documentation
+
+Follow **`documentation-standards.mdc`**. Integrator docs use **version numbers** - not Git branch names.
+
+The **first number** of **`au.gov.nehta:common-library`** is the **Java SE** target, aligned with the HI/MHR client release lines.
+
+| Version | Java | XML stack |
+| ------- | ---- | --------- |
+| **8.0.0** | 8 | **javax** |
+| **11.0.0.1** | 11 | **Jakarta** |
+| **17.0.0.1** | 17 | **Jakarta** |
+| **21.0.0.1** | 21 | **Jakarta** |
+| **24.0.0.1** | 24 | **Jakarta** |
+
+**Git branch mapping (maintainers only - never in integrator docs):**
+
+| Version | Official Git branch |
+| ------- | ------------------- |
+| **8.0.0** | `java-8` |
+| **11.0.0.1** | `java-11` |
+| **17.0.0.1** | `java-17` |
+| **21.0.0.1** | `java-21` |
+| **24.0.0.1** | `java-24` |
+
+## This 8.0.0 line
+
+**`8.0.0-SNAPSHOT`**: Java **8**, **`javax`** XML APIs, **`jaxws-rt` 2.3.7**. Compile depends on **`au.gov.nehta:smi-xsp`** at **`${project.version}`**.
+
+## Build
+
+- JDK **8+**, from repo root: `mvn -B "-Dgpg.skip=true" clean verify` (quote `-D` on PowerShell).
+- Local unpublished builds: install **`smi-xsp`** **8.0.0** / **`${project.version}`** first, then this library.
+
+## Doc split
+
+- **`documentation-standards.mdc`**: implementor-first, Maven Central default, local/OS sections, relative paths, no secrets
+- **`README.md`**: integrators (Maven Central default)
+- **`CONTRIBUTING.md`**: build from source, local SNAPSHOT install
+- **`MAINTAINERS.md`**: POM internals

.cursor/rules/documentation-standards.mdc

@@ -0,0 +1,50 @@
+---
+description: Documentation and build scripts - implementor-first, Maven Central default, no secrets
+alwaysApply: true
+---
+
+# Documentation and build scripts
+
+Applies when writing or editing **README**, **CONTRIBUTING**, integrator guides, **SECURITY**, release notes, **build.*** / **build.xml** header comments, **settings.xml.example**, **local.properties.example**, and similar tracked material.
+
+## Priority: implementors
+
+- Primary audience: developers **consuming** published Maven artifacts.
+- Contributor/maintainer workflow lives in **CONTRIBUTING.md**, **MAINTAINERS.md**, or labelled subsections - not mixed into the integrator main flow.
+- Do not duplicate agent workflow in README or CONTRIBUTING (**AGENTS.md** -> `.cursor/rules/`).
+
+## Default narrative: Maven Central
+
+- Write as if **released** coordinates are on Maven Central (no SNAPSHOT, sibling-repo checkout, or `-P...` profiles in the main integrator path).
+- Use **version numbers** in integrator docs - not Git branch names.
+- SNAPSHOT installs and sibling `mvn install` belong under **Local development** / **Local builds** only.
+
+## Structure
+
+| Where | What |
+| ----- | ---- |
+| README / integrator docs | Dependency, runtime config, capabilities |
+| Local development | Unpublished builds, SNAPSHOT, source-tree prerequisites |
+| By OS (when needed) | Separate **Windows**, **macOS**, **Linux** blocks (wrappers, cleanup, path notes) |
+
+## Paths
+
+- **Relative paths only** (e.g. `src/main/resources/`, `pom.xml` beside repo root).
+- **Never** hardcode machine paths (`C:\...`, `/Users/...`, `~/`, worktree folders) in tracked docs.
+- Override only when strictly required to remove ambiguity - say why.
+
+## Current state only
+
+- No migration, legacy, or branch-history commentary in user-facing docs.
+- Describe **what is true now**; omit "removed", "used to", and repo archaeology in integrator material.
+- **CHANGELOG** entries: current release capabilities; avoid branch names and migration essays in new notes.
+
+## Secrets - MUST NOT
+
+- **Never** put real or plausible **passwords**, **tokens**, **API keys**, **private keys**, or **keystore passphrases** in tracked files (code, comments, examples, docs).
+- Use placeholders or empty values in `.example` files.
+- See **SECURITY.md**.
+
+## Override
+
+These rules may be overridden **only when necessary** to clear ambiguity (e.g. maintainer branch mapping in **MAINTAINERS.md** or `.cursor/rules/`, clearly labelled maintainer-only).

.cursor/rules/multi-branch-worktrees.mdc

@@ -0,0 +1,45 @@
+---
+description: Use git worktree when editing multiple branches of the same repository
+alwaysApply: true
+---
+
+# Multi-branch work - use git worktree
+
+When a task requires **changes on two or more branches of the same Git repository**, use **`git worktree`** - do **not** hop branches with `git checkout` while carrying uncommitted edits or stashes.
+
+## When this applies
+
+- Same-repo edits across release lines (e.g. `java-8`, `java-11`)
+- Applying the same fix to several branches before commit
+- Comparing or building two branches side by side
+
+## When checkout is fine
+
+- Single branch for the whole task
+- Read-only inspection: `git show <branch>:path`
+- Clean working tree and only one target branch
+
+## Workflow
+
+1. **Primary clone** stays on the main working branch; do not stash-and-hop to edit other branches.
+2. **Add a worktree per extra branch** (paths are local - never commit them to tracked docs):
+
+   ```bash
+   git worktree add ../<repo>-<branch-slug> <branch>
+   ```
+
+3. **Edit and commit in each worktree** independently; verify build/tests per branch.
+4. **Remove when done**: `git worktree remove ../<repo>-<branch-slug>` (or `git worktree prune` after manual delete).
+
+## Do not
+
+- `git checkout` other branches with uncommitted changes (Git will block or force stash churn).
+- Stash the same files across multiple branch switches - causes merge conflicts on `stash pop`.
+- Put worktree directory paths in README, CONTRIBUTING, or other tracked docs (see repo **`worktrees.mdc`** / **`documentation-standards.mdc`**).
+
+## Example (maintainer-local paths only)
+
+```bash
+git worktree add <path> java-8
+git worktree add <path> java-11
+```

.cursor/rules/worktrees.mdc

@@ -0,0 +1,37 @@
+---
+description: Worktree paths are local only - versions belong in integrator docs
+alwaysApply: true
+---
+
+# Worktrees (local convenience only)
+
+**`git worktree`** lets a maintainer check out multiple branches of the **same repository** at once. Worktree **directory paths are machine-specific** and must **not** appear in tracked documentation.
+
+## What tracked docs describe
+
+Follow **`documentation-standards.mdc`** (implementor-first, Maven Central default).
+
+| Doc | Audience | Use |
+| --- | --------- | --- |
+| **README**, integrator guides | Implementors | **Maven version** (`8.0.0`), Central coordinates, JAR contents |
+| **CONTRIBUTING** | Contributors | Build from source, **Local builds**, OS-specific steps |
+| **MAINTAINERS**, **`.cursor/rules/`** | Maintainers | POM internals; **branch mapping** only when labelled maintainer-only |
+
+Integrator docs: **version numbers**, not Git branch names. Local/SNAPSHOT flows: **CONTRIBUTING** only.
+
+## Do not put in tracked docs
+
+- Hardcoded worktree or machine paths (`wt/`, `C:\...`, `/Users/...`, `~/`, `this worktree`, `primary clone`)
+- References to **`wt/README.md`** or other local-only layout files
+- "Open folder X to switch branches" - IDE/local workflow, not repo documentation
+
+## Allowed (maintainer-only, when labelled)
+
+- **Git branch mapping** table (version -> branch) in **MAINTAINERS.md** or agent rules
+- Generic worktree example only: `git worktree add <path> <branch>` (placeholder **`<path>`**, never a committed example)
+- Optional **untracked** local notes outside the repo
+
+## When editing docs
+
+1. Identify the **Maven version / release line** the text applies to, not the worktree folder Cursor has open.
+2. Remove or rewrite any committed worktree path tables or branch names in integrator-facing files.

AGENTS.md

@@ -0,0 +1,16 @@
+# Cursor agents
+
+Rules: `.cursor/rules/*.mdc`. Do not duplicate in README or CONTRIBUTING.
+
+| Concern | Rule |
+|---------|------|
+| Documentation and build scripts (implementor-first, Central, local, OS, paths, no secrets) | `documentation-standards.mdc` |
+| common-library scope, build, version lines | `common-library-project.mdc` |
+| Worktrees local only; versions in integrator docs | `worktrees.mdc` |
+| Multi-branch edits in one repo - use worktree, not checkout/stash | `multi-branch-worktrees.mdc` |
+
+Contributors (humans): README, CONTRIBUTING, MAINTAINERS, SECURITY, CHANGELOG.
+
+## Copyright
+
+Copyright 2012 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**.

CHANGELOG.md

@@ -3,6 +3,7 @@
 = 8.0.0 =
 =======
 - Maven **`au.gov.nehta:common-library`** **8.0.0** (Java **8** / **`javax`**). The first number of the Maven version is the targeted Java SE version.
+- Compile dependency **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0**).
 - POM: Eclipse EE4J stack alignment - **`jaxws-rt` 2.3.7**; **`maven-enforcer-plugin`** bans legacy Metro **`webservices-*`** bundles.
 - Build plugins and dependency versions updated to latest Java **8**-compatible releases.
 - Version aligned with the HI/MHR client release lines (`8.0.0`).

CONTRIBUTING.md

@@ -31,11 +31,21 @@ GPG signing is skipped by default (**`-Dgpg.skip=true`**). Release builds: **`-D
 
 ## Dependencies
 
-- Compile: **`com.sun.xml.ws:jaxws-rt`** **2.3.7**, **`au.gov.nehta:smi-xsp`**.
+- Compile: **`com.sun.xml.ws:jaxws-rt`** **2.3.7**, **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0** / **`8.0.0-SNAPSHOT`**).
 - Test: **`junit`**, **`org.apache.santuario:xmlsec`**, **`org.slf4j:slf4j-api`** / **`slf4j-simple`**.
 
 ## Local builds (unpublished artifacts)
 
+Install matching **`smi-xsp`** first (same Java line: **`8.0.0-SNAPSHOT`**), then this library:
+
+```text
+# in smi-xsp-java
+mvn -B "-Dgpg.skip=true" clean install
+
+# in common-library-java
+mvn -B "-Dgpg.skip=true" clean install
+```
+
 **`mvn install`** makes the SNAPSHOT resolvable for any local consumer of **`au.gov.nehta:common-library`** at **`${project.version}`**. Integrators using GA versions from Maven Central do not need a source checkout.
 
 Maintainer notes: **MAINTAINERS.md**.

README.md

@@ -36,13 +36,17 @@ Pick the coordinate that matches your JDK. All published versions are on **[Mave
 
 ## Local development (SNAPSHOT)
 
-This repository builds **`8.0.0-SNAPSHOT`**. To make an unpublished JAR resolvable for other local projects:
+This repository builds **`8.0.0-SNAPSHOT`**. Compile depends on **`au.gov.nehta:smi-xsp`** at **`${project.version}`** (**8.0.0** / **`8.0.0-SNAPSHOT`**). Install unpublished **`smi-xsp`** first when that coordinate is not on Central, then install this library:
 
 ```text
+# smi-xsp-java (same Maven version as this pom.xml)
+mvn -B "-Dgpg.skip=true" clean install
+
+# common-library-java
 mvn -B "-Dgpg.skip=true" clean install
 ```
 
-If Maven warns that a **GA** POM is missing, clear stale **`au/gov/nehta/common-library`** entries in your local Maven repository (folders with only **`.lastUpdated`** files) and reinstall the SNAPSHOT.
+If Maven warns that a **GA** POM is missing, clear stale **`au/gov/nehta/common-library`** or **`au/gov/nehta/smi-xsp`** entries in your local Maven repository (folders with only **`.lastUpdated`** files) and reinstall the SNAPSHOT.
 
 ## Building from source
 

pom.xml

@@ -98,7 +98,8 @@
         <plugin.build.helper.version>3.6.1</plugin.build.helper.version>
         <plugin.gpg.version>3.2.8</plugin.gpg.version>
         <jacoco.version>0.8.14</jacoco.version>
-        <nehta.xsp.lib.version>1.2.1</nehta.xsp.lib.version>
+        <!-- Same Maven version as this artifact and sibling au.gov.nehta:smi-xsp (first number = Java SE). -->
+        <nehta.xsp.lib.version>${project.version}</nehta.xsp.lib.version>
         <maven.shade.plugin.version>3.6.2</maven.shade.plugin.version>
         <!-- Same version as this artifact (SNAPSHOT during dev; GA at release). See README local development. -->
         <hi.wsdl.version>${project.version}</hi.wsdl.version>