diff --git a/.cursor/rules/common-library-project.mdc b/.cursor/rules/common-library-project.mdc new file mode 100644 index 0000000..18dd89a --- /dev/null +++ b/.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 diff --git a/.cursor/rules/documentation-standards.mdc b/.cursor/rules/documentation-standards.mdc new file mode 100644 index 0000000..778c751 --- /dev/null +++ b/.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). diff --git a/.cursor/rules/multi-branch-worktrees.mdc b/.cursor/rules/multi-branch-worktrees.mdc new file mode 100644 index 0000000..aa0018b --- /dev/null +++ b/.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 :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 ../- + ``` + +3. **Edit and commit in each worktree** independently; verify build/tests per branch. +4. **Remove when done**: `git worktree remove ../-` (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 java-8 +git worktree add java-11 +``` diff --git a/.cursor/rules/worktrees.mdc b/.cursor/rules/worktrees.mdc new file mode 100644 index 0000000..7cc5d7a --- /dev/null +++ b/.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 ` (placeholder **``**, 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. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..39ec5f6 --- /dev/null +++ b/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**. diff --git a/CHANGELOG.md b/CHANGELOG.md index 39b475d..a2db882 100644 --- a/CHANGELOG.md +++ b/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`). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7e41dab..b2860fa 100644 --- a/CONTRIBUTING.md +++ b/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**. diff --git a/README.md b/README.md index 8964737..b02a6ba 100644 --- a/README.md +++ b/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 diff --git a/pom.xml b/pom.xml index 2471db9..8772e37 100644 --- a/pom.xml +++ b/pom.xml @@ -98,7 +98,8 @@ 3.6.1 3.2.8 0.8.14 - 1.2.1 + + ${project.version} 3.6.2 ${project.version}