From 25fb28090ff0a24920728d89b232066bf82fe58d Mon Sep 17 00:00:00 2001 From: Gavin Baumanis Date: Tue, 25 Aug 2026 15:05:42 +1000 Subject: [PATCH] Release 8.0.0: Java 8 / javax --- .cursor/rules/documentation-standards.mdc | 50 +++++ .cursor/rules/multi-branch-worktrees.mdc | 45 +++++ .cursor/rules/smi-common-utils-project.mdc | 38 ++++ .cursor/rules/worktrees.mdc | 37 ++++ AGENTS.md | 12 ++ CHANGELOG.md | 33 ++- CONTRIBUTING.md | 46 +++++ MAINTAINERS.md | 34 ++++ README.md | 44 ++-- SECURITY.md | 17 ++ pom.xml | 225 ++++++++++++++------- settings.xml.example | 28 +++ 12 files changed, 510 insertions(+), 99 deletions(-) create mode 100644 .cursor/rules/documentation-standards.mdc create mode 100644 .cursor/rules/multi-branch-worktrees.mdc create mode 100644 .cursor/rules/smi-common-utils-project.mdc create mode 100644 .cursor/rules/worktrees.mdc create mode 100644 AGENTS.md create mode 100644 CONTRIBUTING.md create mode 100644 MAINTAINERS.md create mode 100644 SECURITY.md create mode 100644 settings.xml.example 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/smi-common-utils-project.mdc b/.cursor/rules/smi-common-utils-project.mdc new file mode 100644 index 0000000..89fd158 --- /dev/null +++ b/.cursor/rules/smi-common-utils-project.mdc @@ -0,0 +1,38 @@ +# smi-common-utils-java + +Maven artifact **`au.gov.nehta:smi-common-utils`** - Java utility classes to assist with CDA library development. **Not** facade clients or HI/MHR services. + +## Documentation + +Follow **`documentation-standards.mdc`**. Integrator docs use **version numbers** - not Git branch names. + +The **first number** of the Maven version is the **Java SE** target. + +| Version | Java | Logging | +| ---- | ---- | --- | +| **8.0.0** | 8 | **SLF4J 1.7.x** (javax-compatible) | +| **11.0.0.1** | 11 | **SLF4J 2.x** | + +**Git branch mapping (maintainers only - never in integrator docs):** + +| Version | Official Git branch | +| ---- | ---- | +| **8.0.0** | `java-8` | +| **11.0.0.1** | `java-11` | + +## This 8.0.0 line + +**`8.0.0-SNAPSHOT`**: Java **8**, SLF4J **1.7.36** (last 1.7.x on Maven Central). No JAX-WS or Jakarta dependencies. + +## Build + +- JDK **8+**, from repo root: `mvn -B "-Dgpg.skip=true" clean verify` (quote `-D` on PowerShell). +- Default Surefire: all tests. +- **`-Pcoverage`**: JaCoCo report. + +## 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 +- **`MAINTAINERS.md`**: POM internals 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..0b28948 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,12 @@ +# 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` | +| smi-common-utils scope, build, version lines | `smi-common-utils-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. diff --git a/CHANGELOG.md b/CHANGELOG.md index 35eff75..52fe090 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,15 +1,26 @@ -# Change Log/Revision History +# Changelog -= 1.2.1 = -========= -- Converted to Maven to allow deployment to Maven repo +## 8.0.0 -No record of previous releases available. +- Version line aligned to Java 8 (`maven.compiler.release=8`) +- Distribution migrated to Sonatype Central Portal (`central-publishing-maven-plugin`) +- Updated `slf4j` to 1.7.36 (last 1.7.x on Maven Central) +- Plugin versions updated: compiler 3.15.0, surefire 3.5.5, javadoc 3.12.0, source 3.4.0, gpg 3.2.8 +- GPG signing skipped by default; enabled via `-Prelease` + +## 1.2.1 + +- Converted to Maven +- Replaced external dependencies with Maven ones + +## 1.2.0 + +- Added support for JVM 1.7_21+ + +## 1.0 -= 1.2.0 = -========= -17 Feb 2010 - -= 1.0 = -======= - Initial release + +## Copyright + +Copyright 2009 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4750d38 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,46 @@ +# Contributing + +## Prerequisites + +- JDK 8 (or any later JDK with `--release 8` support) +- Maven 3.6+ + +## Local builds + +``` +# Windows +mvn -B "-Dgpg.skip=true" clean verify + +# macOS / Linux +mvn -B -Dgpg.skip=true clean verify +``` + +## Local SNAPSHOT install + +To install to your local Maven repository without signing: + +``` +mvn -B "-Dgpg.skip=true" clean install +``` + +## Running tests + +Tests run automatically during `verify`. To skip: + +``` +mvn -B "-Dgpg.skip=true" -DskipTests clean package +``` + +## Code style + +- Java 8 source and target (`maven.compiler.release=8`) +- All source files must be ASCII only +- SLF4J 1.7.x API; no Jakarta (`jakarta.*`) dependencies on this branch + +## Pull requests + +Target the `java-8` branch. Ensure `mvn verify` passes before opening a PR. + +## Copyright + +Copyright 2009 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/MAINTAINERS.md b/MAINTAINERS.md new file mode 100644 index 0000000..0e16026 --- /dev/null +++ b/MAINTAINERS.md @@ -0,0 +1,34 @@ +# Maintainers + +## Artifact + +`au.gov.nehta:smi-common-utils` - published to Maven Central via Sonatype Central Portal. + +## Version lines + +| Version | Java | Branch | +| ------------ | ------------ | --------- | +| **8.0.0** | 8 / javax | `java-8` | +| **11.0.0.1** | 11 / Jakarta | `java-11` | + +## Key dependency + +| Property | Value | +| --------------- | --------------------------------------------------- | +| `slf4j.version` | `1.7.36` (last 1.7.x on Central; Java 8 compatible) | + +To update: change `slf4j.version` in `pom.xml` properties, run `mvn verify`. + +## Release process + +1. Ensure `java-8` branch is green. +2. `mvn -B release:prepare release:perform -Prelease` (GPG key required). +3. Sonatype Central Portal auto-publishes after closing. + +## Publishing credentials + +`settings.xml` with `` - see `settings.xml.example`. + +## Copyright + +Copyright 2009 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/README.md b/README.md index 0ceb09d..530a1e8 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,34 @@ -# SMI Common Utils Library +# smi-common-utils - SMI Common Utilities -This is a collection of utility classes helpful for CDA libraries. +Java utility classes to assist with CDA library development for the Australian Digital Health Agency. -Building and running the code -============================= +## Dependency (Maven Central) -The project is supplied with a Maven pom.xml file. Use Maven to build the code. +```xml + + au.gov.nehta + smi-common-utils + 8.0.0 + +``` -Source code -=========== +## Runtime requirements -The source code is the src/main/java directory structure. +- Java 8 or later +- SLF4J API is a compile dependency; include an SLF4J binding on your classpath at runtime -Licensing -========= +## Building from source -Copyright 2009 NEHTA +See **CONTRIBUTING.md**. -Copyright 2021 ADHA +## Local development -Licensed under the NEHTA/ADHA Open Source (Apache) License; you may not use this -file except in compliance with the License. A copy of the License is in the -'LICENSE.txt' file, which should be provided with this work. +See **CONTRIBUTING.md** - Local builds section. -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, WITHOUT -WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the -License for the specific language governing permissions and limitations -under the License. +## License + +Apache License 2.0 - see **LICENSE.txt**. + +## Copyright + +Copyright 2009 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..635569a --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,17 @@ +# Security + +## Reporting a vulnerability + +Report security vulnerabilities to: **admin.opensource@digitalhealth.gov.au** + +Do not open a public GitHub issue for security vulnerabilities. + +## Supported versions + +| Version | Supported | +| ------- | --------- | +| 8.0.0 | Yes | + +## Copyright + +Copyright 2009 NEHTA. Copyright 2021-2026 ADHA. Apache License 2.0 - see **LICENSE.txt**. diff --git a/pom.xml b/pom.xml index 926907a..e81b5f6 100644 --- a/pom.xml +++ b/pom.xml @@ -1,10 +1,15 @@ + 4.0.0 au.gov.nehta smi-common-utils - 1.2.2-SNAPSHOT + 8.0.0-SNAPSHOT SMI Common Utils Java classes to assist with CDA library development https://github.com/AuDigitalHealth/smi-common-utils-java @@ -12,7 +17,7 @@ Apache License, Version 2.0 - http://www.apache.org/licenses/LICENSE-2.0.txt + https://www.apache.org/licenses/LICENSE-2.0.txt repo @@ -22,8 +27,8 @@ Admin Open Source admin.opensource@digitalhealth.gov.au Australian Digital Health Agency - www.digitalhealth.gov.au - www.digitalhealth.gov.au + https://www.digitalhealth.gov.au/ + https://www.digitalhealth.gov.au/ Admin @@ -32,55 +37,107 @@ - scm:git:https://github.com/AuDigitalHealth/smi-common-utils-java.git - - - scm:git:https://github.com/AuDigitalHealth/smi-common-utils-java.git - - https://github.com/AuDigitalHealth/smi-common-utils-java.git - smi-common-utils-1.2.1 + scm:git:${scm.repo.url} + scm:git:${scm.repo.url} + ${scm.repo.url} + ${scm.tag} + + GitHub + https://github.com/AuDigitalHealth/smi-common-utils-java/issues + + + + GitHub Actions + https://github.com/AuDigitalHealth/smi-common-utils-java/actions + + - nexus-snapshots - https://oss.sonatype.org/content/repositories/snapshots + central + https://central.sonatype.com/repository/maven-snapshots/ - nexus-releases - https://oss.sonatype.org/service/local/staging/deploy/maven2 + central + https://central.sonatype.com + + 8 + UTF-8 + ${encoding} + ${encoding} + ${encoding} + ${encoding} + false + true + https://github.com/AuDigitalHealth/smi-common-utils-java.git + HEAD + true + false + deploy + release + @{project.artifactId}-@{project.version} + true + true + [maven-release-plugin] + + 1.7.36 + 4.13.2 + 3.5.0 + 3.15.0 + 3.5.5 + 3.12.0 + 3.4.0 + 3.1.4 + 3.3.1 + 0.9.0 + 3.2.8 + 0.8.14 + -Xmx1024m + + org.slf4j slf4j-api - 1.7.30 + ${slf4j.version} org.slf4j slf4j-simple - 1.7.30 + ${slf4j.version} + runtime + + + junit + junit + ${junit.version} + test - - 1.8 - 1.8 - UTF-8 - ${encoding} - ${encoding} - ${encoding} - ${encoding} - - + + org.apache.maven.plugins + maven-clean-plugin + ${plugin.clean.version} + + true + false + true + + org.apache.maven.plugins maven-gpg-plugin - 1.6 + ${plugin.gpg.version} + + ${gpg.skip} + sign-artifacts @@ -94,12 +151,13 @@ org.apache.maven.plugins maven-javadoc-plugin - 3.2.0 + ${plugin.javadoc.version} - true - + false none + false ${encoding} + 8 @@ -113,12 +171,12 @@ org.apache.maven.plugins maven-source-plugin - 3.2.1 + ${plugin.source.version} attach-sources - jar + jar-no-fork @@ -126,75 +184,106 @@ org.apache.maven.plugins maven-deploy-plugin - 3.0.0-M1 + ${plugin.deploy.version} true - org.sonatype.plugins - nexus-staging-maven-plugin - 1.6.8 + org.sonatype.central + central-publishing-maven-plugin + ${plugin.central.publishing.version} true - nexus-releases - https://oss.sonatype.org/ - true - - - - org.apache.maven.plugins - maven-surefire-report-plugin - 3.0.0-M4 - - false - CDA Schema Java Tests Output - ${basedir}/target/surefire-reports + central + true maven-surefire-plugin - 2.22.2 + ${plugin.surefire.version} + ${skipTests} UTF-8 true - 3 - true - -Xmx1024m + ${argLine} org.apache.maven.plugins maven-release-plugin - 3.0.0-M1 + ${plugin.release.version} - mavenization false - release - true - false - deploy + ${release.profiles} + ${release.localCheckout} + ${release.dryRun} + ${release.goals} + ${release.tagNameFormat} + ${release.pushChanges} + ${release.remoteTagging} + ${release.scmCommentPrefix} maven-compiler-plugin - 3.8.1 + ${plugin.compiler.version} + ${maven.compiler.release} + ${project.build.sourceEncoding} + none -Xlint:unchecked - -verbose - ${maven.compiler.source} - ${maven.compiler.target} - ${project.build.sourceEncoding} - true + true lines,vars,source true true - true - \ No newline at end of file + + + release + + false + + + + dev-javadoc-off + + true + + + + coverage + + + + org.jacoco + jacoco-maven-plugin + ${jacoco.version} + + + jacoco-prepare-agent + + prepare-agent + + + + jacoco-report + verify + + report + + + + + + + + + + diff --git a/settings.xml.example b/settings.xml.example new file mode 100644 index 0000000..fee3e9f --- /dev/null +++ b/settings.xml.example @@ -0,0 +1,28 @@ + + + + +