From 94cc2f71925ce00513082deb4b14cc25f664c641 Mon Sep 17 00:00:00 2001 From: SpaiR Date: Mon, 27 Jul 2026 09:04:36 +0300 Subject: [PATCH 1/6] docs: move CONTRIBUTING.md to repo root Update references in AGENTS.md now that it's no longer under docs/. --- AGENTS.md | 4 ++-- docs/CONTRIBUTING.md => CONTRIBUTING.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) rename docs/CONTRIBUTING.md => CONTRIBUTING.md (98%) diff --git a/AGENTS.md b/AGENTS.md index 61e22ab5..76a71b90 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,7 +16,7 @@ upgrading submodules, and the codegen-internals conventions. The everyday conven - **`.claude/docs/patterns.md`** — recurring patterns when adding to the binding (the codegen loop, annotated stubs, struct wrappers, out-parameter `Im*` wrappers, module boundaries, application lifecycle). -- **`docs/CONTRIBUTING.md`** — PR/commit workflow. Includes the conventional-commit +- **`CONTRIBUTING.md`** — PR/commit workflow. Includes the conventional-commit format and, importantly, the **`Co-authored-by` trailer rule for AI-assisted commits** and the "you are responsible for the change" rule. Read it before opening a PR. @@ -198,7 +198,7 @@ Use `providers.exec { ... }` for shell-outs, never `.execute()`. Capture resolve The full commit-message format, the conventional-commit types/scopes, and the mandatory `Co-authored-by` trailer for AI-assisted commits are documented in -`docs/CONTRIBUTING.md` — follow that. The rule that submodule bumps, Gradle/deps +`CONTRIBUTING.md` — follow that. The rule that submodule bumps, Gradle/deps bumps, and codegen-tooling changes each go in their own PR is in `.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work"). diff --git a/docs/CONTRIBUTING.md b/CONTRIBUTING.md similarity index 98% rename from docs/CONTRIBUTING.md rename to CONTRIBUTING.md index 97b2cb71..0511db64 100644 --- a/docs/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ Similarly, a Deprecation section should start with "DEPRECATED: " followed by a ## Contributing with AI Agents AI coding agents (Claude Code, Copilot, Cursor, Codex, Gemini, etc.) are welcome to assist with contributions. -See [AGENTS.md](../AGENTS.md) for the canonical guidance on how AI agents should work in this repo (golden rules, +See [AGENTS.md](AGENTS.md) for the canonical guidance on how AI agents should work in this repo (golden rules, codegen workflow, build commands, gotchas). Two extra rules apply on top of the regular contribution flow: From ef8f1142e76a34d17f23e4f354c38983b2ce50c3 Mon Sep 17 00:00:00 2001 From: SpaiR Date: Mon, 27 Jul 2026 09:04:41 +0300 Subject: [PATCH 2/6] docs: trim CLAUDE.md to defer entirely to AGENTS.md Avoid duplicating the summary list, which drifts from AGENTS.md as it changes. --- CLAUDE.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 20acacc8..8acc30e3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,22 +2,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. -See [AGENTS.md](AGENTS.md) — it is the canonical guidance for AI agents in this repo and covers everything Claude Code -needs: +Read [AGENTS.md](AGENTS.md) — it is the canonical and authoritative guidance for AI agents in this repo, covering +project layout, build & test commands, the codegen workflow, submodule bumps, gotchas, conventions, and the PR process. -- What the repo is (JNI binding for Dear ImGui + extensions, codegen-driven multi-module Gradle build). -- Project layout (`imgui-binding/`, `imgui-lwjgl3/`, `imgui-app/`, `buildSrc/`, `include/` submodules, etc.). -- The **golden rule**: never edit `imgui-binding/src/generated/java/` — it is regenerated from annotated sources in - `imgui-binding/src/main/java/`. Workflow: edit source → `./gradlew :imgui-binding:generateApi` → commit both trees - together. -- Build & test commands (`compileJava`, `javadoc`, `generateApi`, `generateAst`, `generateLibs`, `build`) and the visual - smoke-test flow for backend/font/example changes. -- Submodule-bump procedure for Dear ImGui and extensions, including AST regeneration scope rules. -- Gotchas: doclint-vs-C++ comment patterns, vendor patches, `GenerateLibs.groovy` literal-string rewrites, AST drift, - rebase strategy for codegen output, submodule sync after branch switch, `bin/` ownership by CI. -- Design conventions (dual font loader: stb_truetype + FreeType). -- Codegen-internals conventions for `buildSrc/` (Spoon generic-type bounds, Gradle 9 configuration cache). -- PR workflow and merge-ordering guidance. +The golden rule from there, repeated because it is easy to trip over: **never edit +`imgui-binding/src/generated/java/`** — it is regenerated from annotated sources in `imgui-binding/src/main/java/`. -Treat `AGENTS.md` as authoritative. If something here ever conflicts with `AGENTS.md`, `AGENTS.md` wins — update it -there, not here. +If anything here ever conflicts with `AGENTS.md`, `AGENTS.md` wins — update it there, not here. From f54fef940415c936f23e41f55de709cfa4c6b096 Mon Sep 17 00:00:00 2001 From: SpaiR Date: Mon, 27 Jul 2026 09:04:45 +0300 Subject: [PATCH 3/6] chore: ignore per-module bin/ output from Eclipse/VS Code Java builds Root bin/ holds tracked native libs, so only ignore */bin/. --- .gitignore | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.gitignore b/.gitignore index aee6e667..39df9edc 100644 --- a/.gitignore +++ b/.gitignore @@ -16,6 +16,10 @@ logs/ *.iws .idea/ +# Eclipse / VS Code Java (Buildship) compile output. +# Only per-module bin/ — the root bin/ holds tracked native libs. +/*/bin/ + # Package Files # *.jar *.war From bd42febe85061fefecdf2450648651e40a79c613 Mon Sep 17 00:00:00 2001 From: SpaiR Date: Mon, 27 Jul 2026 10:08:46 +0300 Subject: [PATCH 4/6] docs: rewrite CONTRIBUTING.md and align PR template MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The old file was mostly the generic contributing template: an empty "open a new issue" link, a bug-report section duplicating the issue forms, and commit rules that no longer matched the history — `build` listed as both a type and a scope, no `deps` scope, and a mandatory 20-character body that most `fix`/`chore` commits ignore. - add quick start, prerequisites, and the checks to run before pushing - lift the rules that actually block review to the top: never edit src/generated, never commit bin/ natives, one topic per PR, doclint - extend commit types to feat|fix|perf|refactor|docs|test|build|chore| revert, and scopes from 3 to 13 matching the module layout - add PR rules: the title must be a valid commit header since PRs are squash-merged, plus body sections, label mapping, and CI coverage - document the release procedure and the versioning scheme — MAJOR.MINOR tracks Dear ImGui, so the version can never signal a breaking change - point AGENTS.md and README at CONTRIBUTING.md as the commit/PR/release authority, and give the PR template matching sections Co-authored-by: Claude --- .github/pull_request_template.md | 20 +- AGENTS.md | 33 ++- CONTRIBUTING.md | 443 ++++++++++++++++++++++++------- README.md | 11 +- 4 files changed, 392 insertions(+), 115 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 3d68ff00..3ac11f9c 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,15 +1,25 @@ - +## Summary + + + ## Type of change - + - [ ] Minor changes or tweaks (quality of life stuff) - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) - [ ] This change requires a documentation update + +## Notes for reviewer + + + + diff --git a/AGENTS.md b/AGENTS.md index 76a71b90..56969c12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,9 +16,13 @@ upgrading submodules, and the codegen-internals conventions. The everyday conven - **`.claude/docs/patterns.md`** — recurring patterns when adding to the binding (the codegen loop, annotated stubs, struct wrappers, out-parameter `Im*` wrappers, module boundaries, application lifecycle). -- **`CONTRIBUTING.md`** — PR/commit workflow. Includes the conventional-commit - format and, importantly, the **`Co-authored-by` trailer rule for AI-assisted commits** - and the "you are responsible for the change" rule. Read it before opening a PR. +- **`CONTRIBUTING.md`** — the human-facing contributor guide, and the authority on + everything commit- and release-shaped: the conventional-commit types/scopes tables, PR + title and body rules (PRs are squash-merged, so the **PR title must be a valid commit + header**), label mapping, the versioning scheme (version tracks Dear ImGui, so it can + never signal a break), the release procedure, and — importantly — the **`Co-authored-by` + trailer rule for AI-assisted commits** plus the "you are responsible for the change" + rule. Read it before writing a commit message or opening a PR. If anything below conflicts with those files, the dedicated file wins — update it there, not here. @@ -196,11 +200,24 @@ Use `providers.exec { ... }` for shell-outs, never `.execute()`. Capture resolve ## PR workflow -The full commit-message format, the conventional-commit types/scopes, and the -mandatory `Co-authored-by` trailer for AI-assisted commits are documented in -`CONTRIBUTING.md` — follow that. The rule that submodule bumps, Gradle/deps -bumps, and codegen-tooling changes each go in their own PR is in -`.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work"). +`CONTRIBUTING.md` is the authority here — follow it, don't paraphrase it: + +- **Commit messages** → "Commit message format". Types (`feat|fix|perf|refactor|docs|test|build|chore|revert`) + and scopes (`api|native|generator|vendor|lwjgl3|app|example|deps|ci|gradle|readme|agents|contributing`) + are fixed tables — pick from them, never invent a scope. `!` in the header requires a + `BREAKING CHANGE:` footer. +- **PR title** → must be a valid commit header; PRs are squash-merged and the title becomes + the subject line on `main`. Also apply the type label from the mapping table there. +- **AI-assisted commits** → the `Co-authored-by` trailer is mandatory, family-level model name + only. Strip versioned model names, session URLs, and "Generated with …" lines that tooling + adds by default, and check the trailer survives the squash. +- **Releases** → "Releases". Tag-driven (`git describe` is the version of record), version + tracks Dear ImGui's `MAJOR.MINOR`, so a breaking change is only ever visible via `!`, the + footer, and the release notes. Never cut a release on stale `bin/` natives. + +The rule that submodule bumps, Gradle/deps bumps, and codegen-tooling changes each go in their +own PR is in `.claude/rules/guardrails.md` ("Don't merge submodule bumps with feature work") +and restated in `CONTRIBUTING.md` § "Before you start". Operational guidance on top of those: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0511db64..b8eeee0d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,105 +1,240 @@ # Contributing to imgui-java -We love your input! We want to make contributing to this project as easy and transparent as possible, whether it's: -- Reporting a bug -- Discussing the current state of the code -- Submitting a fix -- Proposing new features -- Becoming a maintainer +Contributions are welcome — bug reports, missing-binding requests, fixes, new binding surface, backend work, and doc +improvements alike. -## We Develop with Github -We use github to host code, to track issues and feature requests, as well as accept pull requests. +This document covers the mechanics: how to build the project, the rules that decide whether a patch is reviewable, the +commit format, the PR flow, and how releases are cut. -## We Use [Github Flow](https://docs.github.com/en/get-started/quickstart/github-flow), So All Code Changes Happen Through Pull Requests -Pull requests are the best way to propose changes to the codebase (we use [GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)). We actively welcome your pull requests: +- **Contents** + - [Before you start](#before-you-start) + - [Quick start](#quick-start) + - [Development loop](#development-loop) + - [Commit message format](#commit-message-format) + - [Pull requests](#pull-requests) + - [Releases](#releases) + - [Contributing with AI agents](#contributing-with-ai-agents) + - [Reporting bugs](#reporting-bugs) + - [License](#license) -1. Fork the repo and create your branch from `main`. -2. Make sure your code lints. -3. Issue that pull request! +## Before you start -## Commit Message Format +Four rules cause most of the rejected patches in this repo. Read them before writing code. -*This specification is inspired by and adapts -the [Angular commit message format](https://github.com/angular/angular/blob/92113d73dd38d0285e25e8d678c240cf4aa8834a/CONTRIBUTING.md#commit) -and [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) practises.* +### 1. Never edit `imgui-binding/src/generated/java/` -We have very precise rules over how our Git commit messages must be formatted. -This format leads to **easier to read commit history**. +The Java API is **codegen-driven**. Hand-written annotated stubs live in `imgui-binding/src/main/java/`; the Spoon-based +generator in `buildSrc/` expands them into `imgui-binding/src/generated/java/`. Both trees are committed, but only the +first is a source. Edits to the generated tree are silently reverted on the next `generateApi` run. -Each commit message consists of a **header**, a **body**, and a **footer**. +```bash +# edit imgui-binding/src/main/java/... +./gradlew :imgui-binding:generateApi +git add imgui-binding/src/main/java imgui-binding/src/generated/java +``` + +Source and regenerated output belong in the **same commit** — a commit that changes one without the other leaves the +tree inconsistent. + +### 2. Never commit native binaries + +`bin/libimgui-java64.*` and `bin/imgui-java64.dll` are owned by CI. The `update-bin` job rebuilds them on `main` after a +binding change and commits them as `[ci skip] update native binaries`. Locally built natives must not be staged. + +Use `git add ` instead of `git add -A` / `git add .` — bulk staging picks up `bin/` and +`imgui-binding/build/libsNative/` by accident. + +### 3. One topic per pull request + +Submodule bumps, Gradle/dependency bumps, codegen-tooling changes, and new API surface each go in their own PR. A +submodule bump already produces a large regenerated diff; adding a feature on top makes it unreviewable and makes CI +failures ambiguous. Land the bump first, add the new surface in a follow-up. + +### 4. Javadoc must pass doclint + +Doc comments in the binding are copied verbatim from Dear ImGui's C++ headers, and JDK 17's doclint rejects anything +that parses as broken HTML. CI runs javadoc as part of the build; a doc-comment typo fails the whole pipeline. + +Wrap operators in `{@code ...}` — `<`, `>`, `&`, `&&`, `||`, `->` all break otherwise. Keep `@link` targets, `@param`, +and `@return` in sync with the current method signature. +## Quick start +```bash +git clone --recurse-submodules https://github.com/SpaiR/imgui-java.git +cd imgui-java +./gradlew :example:run ``` -
- - - -