From 4ba5890f254f558517cb1d083194e2643cc239af Mon Sep 17 00:00:00 2001 From: brianhdk Date: Sun, 15 Feb 2026 20:54:18 +0100 Subject: [PATCH 1/2] feat: upgrade and create agents.md --- .github/workflows/CI.yml | 10 ++-- .github/workflows/publish.yml | 8 +-- AGENTS.md | 98 +++++++++++++++++++++++++++++++++++ DEVELOPMENT.md | 4 +- Generator/Generator.csproj | 2 +- 5 files changed, 110 insertions(+), 12 deletions(-) create mode 100644 AGENTS.md diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index 8a69a689..defd5a4c 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -9,18 +9,18 @@ jobs: steps: - name: Checkout - uses: actions/checkout@v1 + uses: actions/checkout@v6 - - name: Setup .NET 7 - uses: actions/setup-dotnet@v1 + - name: Setup .NET 10 + uses: actions/setup-dotnet@v5 with: - dotnet-version: '9.0.x' + dotnet-version: '10.0.x' - name: Generate Java classes run: ./generate.sh - name: Set up JDK 17 - uses: actions/setup-java@v3 + uses: actions/setup-java@v4 with: java-version: '17' distribution: 'temurin' diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 300354eb..71c3ba8f 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -17,12 +17,12 @@ jobs: steps: - name: Checkout source code - uses: actions/checkout@v4 + uses: actions/checkout@v6 - - name: Setup .NET 7 - uses: actions/setup-dotnet@v3 + - name: Setup .NET 10 + uses: actions/setup-dotnet@v5 with: - dotnet-version: '9.0.x' + dotnet-version: '10.0.x' - name: Generate Java classes run: ./generate.sh diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..d5983684 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,98 @@ +# AGENTS.md + +## Purpose +This file is the operating guide for contributors and coding agents working in `relewise-sdk-java`. + +The repository is a Java SDK with generated client/models and Maven-based build/release workflows. Follow this guide to keep changes scoped, verifiable, and CI-aligned. + +## Repository Map +- `src/pom.xml`: Maven project manifest (packaging, test, release profile). +- `src/src/main/java/com/relewise/client`: Java SDK source. +- `src/src/test/java/com/relewise/client`: JUnit tests. +- `Generator`: .NET generator project for Java SDK code. +- `.github/workflows`: CI, publish, and Trello workflows. +- `generate.ps1` / `generate.sh`: generation entry points. +- `DEVELOPMENT.md`: local development notes. +- `PUBLISH.md`: release workflow and troubleshooting notes. +- `openapitools.json`, `swagger.json`: generation/reference assets. + +## Core Working Conventions +- Run generation scripts from repository root. +- Run Maven commands against `src/pom.xml`. +- Keep changes minimal and related to the task. +- Do not commit secrets (`DATASET_ID`, `API_KEY`, Sonatype/GPG credentials). +- Treat generator output as generated code: + - `src/src/main/java/com/relewise/client/model` is generator-owned. + - Client layers in `src/src/main/java/com/relewise/client` are also generated by current pipeline. +- Prefer generator changes + regeneration over manual edits in generated files. + +## Generation Workflow +Prerequisite: .NET 10 SDK or newer. + +Use one of: + +```powershell +./generate.ps1 +``` + +```bash +./generate.sh +``` + +The generator writes SDK code into `src/src/main/java/com/relewise/client`. + +## Runbook +Generate SDK code: + +```powershell +./generate.ps1 +``` + +```bash +./generate.sh +``` + +Build package: + +```powershell +mvn --batch-mode -DskipTests package --file src/pom.xml +``` + +Generate `project.properties` for runtime version metadata: + +```powershell +mvn resources:resources --file src/pom.xml +``` + +Run tests: + +```powershell +mvn --batch-mode test --file src/pom.xml +``` + +## Testing and Credentials +- Tests use `DATASET_ID` and `API_KEY` from environment (`TestBase`). +- CI injects credentials from secrets. +- If credentials are unavailable locally, explicitly report integration-style test coverage as not run. + +## Validation Policy (CI-Aligned, Pragmatic) +- Required for normal changes: + - Regenerate when touching generator-owned surfaces. + - Run package + test commands against `src/pom.xml`. +- Required for behavior/API changes: + - Run tests covering affected request/response flows. +- Required for release/publish changes: + - Validate relevant release-profile commands as appropriate. + - Follow `PUBLISH.md` as source of truth for release operations. + +## PR Expectations +Each PR should include: +- Scope: what changed and why. +- Risk notes: behavior or release surface impacted. +- Validation: exact commands run and results. +- Generation note: whether generation scripts were run. + +## Known Pitfalls +- Maven project lives under `src`; root-level `mvn` without `--file src/pom.xml` is wrong. +- Skipping `mvn resources:resources --file src/pom.xml` can leave client version metadata stale. +- Manual edits to generated files create drift on next generation run. diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 9933fa0d..8f31b956 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -6,8 +6,8 @@ This document describes the process for running this application on your local c This project uses .NET to automatically generate the models used in the Java client. -To run the generator you need to have .NET 7 or newer installed on your machine. [Download .NET 7](https://dotnet.microsoft.com/en-us/download/dotnet/7.0) +To run the generator you need to have .NET 10 or newer installed on your machine. [Download .NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) Then to generate the models and clients of the SDK run `generate.ps1` if you're on Windows, else run `generate.sh`. ## Development experience -For the best experience with developing on the SDK we recommend to use a dedicated Java IDE. \ No newline at end of file +For the best experience with developing on the SDK we recommend to use a dedicated Java IDE. diff --git a/Generator/Generator.csproj b/Generator/Generator.csproj index 15f3be22..3b330a95 100644 --- a/Generator/Generator.csproj +++ b/Generator/Generator.csproj @@ -2,7 +2,7 @@ Exe - net9.0 + net10.0 enable enable From 040477b40e2b484b2dfda5958132bc330cf31e7a Mon Sep 17 00:00:00 2001 From: brianhdk Date: Mon, 16 Feb 2026 05:47:42 +0100 Subject: [PATCH 2/2] skill to update sdk --- .agents/skills/update-sdk/SKILL.md | 186 +++++++++++++++++++ .agents/skills/update-sdk/agents/openai.yaml | 4 + AGENTS.md | 15 ++ 3 files changed, 205 insertions(+) create mode 100644 .agents/skills/update-sdk/SKILL.md create mode 100644 .agents/skills/update-sdk/agents/openai.yaml diff --git a/.agents/skills/update-sdk/SKILL.md b/.agents/skills/update-sdk/SKILL.md new file mode 100644 index 00000000..7345d865 --- /dev/null +++ b/.agents/skills/update-sdk/SKILL.md @@ -0,0 +1,186 @@ +--- +name: update-sdk +description: Regenerate relewise-sdk-java from the Generator project with a strict git and PR flow. Use when asked to update generated Java SDK code. Require a Trello card URL, run clean-main preflight checks, create a timestamped chore branch, run generation and validation, then push and open a PR with the Trello URL as the first line. +--- + +# Update SDK (Java) + +## Goal +Regenerate SDK code in `src/src/main/java/com/relewise/client` from `Generator`, validate the result, and deliver a reviewed PR to `main`. + +## Required Input +Require a Trello card URL before running SDK update work. + +If the request does not include a Trello URL: +- Ask for it. +- Do not continue until it is provided. + +## Preflight Git Safety +Run from repository root. + +1. Require a clean worktree: +```powershell +git status --porcelain +``` +Abort when any output exists. + +2. Ensure `origin` exists: +```powershell +git remote get-url origin +``` +Abort on failure. + +3. Fetch refs: +```powershell +git fetch origin --prune +``` +Abort on failure. + +4. Switch to `main`: +```powershell +git switch main +``` +Abort if switch is not safe. + +5. Fast-forward `main`: +```powershell +git pull --ff-only origin main +``` +Abort if not fast-forward. + +Do not continue when any preflight step fails. + +## Branch Creation +Use a timestamped branch: + +```powershell +$stamp = Get-Date -Format 'yyyyMMdd-HHmm' +$branchName = "chore/update-sdk-$stamp" +``` + +Abort if branch exists: + +```powershell +git show-ref --verify --quiet "refs/heads/$branchName" +git ls-remote --exit-code --heads origin $branchName +``` + +Create and switch: + +```powershell +git switch -c $branchName +``` + +## SDK Regeneration +Regenerate SDK code: + +```powershell +./generate.ps1 +``` + +Alternative on non-Windows: +```bash +./generate.sh +``` + +## Expected Changes Check +Inspect changed files and ensure the update is coherent. + +Expected change locations: +- `src/src/main/java/com/relewise/client/model/*` generated model files +- generated client surfaces in `src/src/main/java/com/relewise/client/*` +- generator changes only when intentionally included + +If unrelated files changed unexpectedly, stop and investigate. + +## Validation (Required) +Run from repository root: + +1. Package: +```powershell +mvn --batch-mode -DskipTests package --file src/pom.xml +``` + +2. Resource/version metadata: +```powershell +mvn resources:resources --file src/pom.xml +``` + +3. Tests: +```powershell +mvn --batch-mode test --file src/pom.xml +``` + +Integration-heavy tests depend on `DATASET_ID` and `API_KEY`. + +When credentials are unavailable, run a credential-independent subset and report integration-heavy coverage as not run: + +```powershell +mvn --batch-mode -Dtest=ClientConstructionTest,DateTimeSerializationTest test --file src/pom.xml +``` + +## Acceptance Criteria +Treat update as successful only when: +- generation succeeds (`generate.ps1` or `generate.sh`) +- package/resources commands succeed +- test command(s) pass for available credentials +- changed files are expected and reviewable + +## Commit, Push, and Pull Request +1. Commit SDK update changes: +```powershell +git add . +git commit -m "chore(java): update sdk generation ($stamp)" +``` + +2. Push branch: +```powershell +git push -u origin $branchName +``` + +3. Create PR to `main`. + +Preferred flow with GitHub CLI: +```powershell +$prBodyPath = ".\\update-sdk-pr-body.md" +@" +$TrelloCardUrl + +## Summary +- Regenerated Java SDK code via Generator +- Updated generated models/client surfaces + +## Validation +- `./generate.ps1`: +- `mvn --batch-mode -DskipTests package --file src/pom.xml`: +- `mvn resources:resources --file src/pom.xml`: +- `mvn --batch-mode test --file src/pom.xml`: +- `mvn --batch-mode -Dtest=ClientConstructionTest,DateTimeSerializationTest test --file src/pom.xml`: + +## Notes +- +"@ | Set-Content $prBodyPath + +$prUrl = gh pr create --base main --head $branchName --title "chore(java): update sdk generation ($stamp)" --body-file $prBodyPath +if ($LASTEXITCODE -ne 0) { throw 'gh pr create failed.' } +Write-Host "PR URL: $prUrl" +``` + +Manual fallback: +```powershell +git push -u origin $branchName +Write-Host "Create PR: https://github.com/Relewise/relewise-sdk-java/compare/main...$branchName?expand=1" +Write-Host "PR title: chore(java): update sdk generation ($stamp)" +Write-Host "PR body file: $prBodyPath" +``` + +Keep the Trello URL as the first line of the PR description. + +## Output Expectations +Provide a final summary with: +- Trello URL used +- branch name +- changed file groups +- validation command results +- pushed branch URL +- PR URL, or exact manual fallback instructions diff --git a/.agents/skills/update-sdk/agents/openai.yaml b/.agents/skills/update-sdk/agents/openai.yaml new file mode 100644 index 00000000..c8946619 --- /dev/null +++ b/.agents/skills/update-sdk/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Update SDK" + short_description: "Regenerate relewise-sdk-java code and open Trello-linked PR" + default_prompt: "Use $update-sdk to regenerate relewise-sdk-java, validate build and tests, and create a branch and PR with the Trello URL as the first line." diff --git a/AGENTS.md b/AGENTS.md index d5983684..432b0fdd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,12 @@ The repository is a Java SDK with generated client/models and Maven-based build/ - `PUBLISH.md`: release workflow and troubleshooting notes. - `openapitools.json`, `swagger.json`: generation/reference assets. +## Repository Skills +- `update-sdk`: + - Location: `.agents/skills/update-sdk/SKILL.md` + - Use when asked to regenerate generated SDK code from `Generator`. + - This skill enforces Trello URL pre-requisite, clean-main preflight checks, timestamped chore branch creation, validation commands, and Trello-first PR descriptions. + ## Core Working Conventions - Run generation scripts from repository root. - Run Maven commands against `src/pom.xml`. @@ -85,6 +91,15 @@ mvn --batch-mode test --file src/pom.xml - Validate relevant release-profile commands as appropriate. - Follow `PUBLISH.md` as source of truth for release operations. +## SDK Update Guidance +For generation-driven SDK refresh tasks, prefer using the `update-sdk` skill: + +```text +$update-sdk +``` + +Use `update-sdk` when the goal is regenerating Java SDK code and opening a branch/PR flow tied to a Trello card. + ## PR Expectations Each PR should include: - Scope: what changed and why.