Senzing Java Coding Standards

The canonical home for the formatting rules, build configuration, FAQ content, and tooling shared across Senzing Java projects. Consumer projects mount this repo as a git submodule at .java-coding-standards/ and reference its files directly — there is no published artifact (no Maven Central, no PyPI). One submodule pin gives a project the rules, the docs, the FAQ corpus, the formatter profile, the bulk-format scripts, and the FAQ MCP server in lockstep.

What's in here

checkstyle/
    senzing-checkstyle.xml                — checkstyle config consumed by
                                             maven-checkstyle-plugin
    senzing-checkstyle-suppressions.xml   — shared base; consumer projects
                                             layer their own
                                             checkstyle-suppressions-local.xml

docs/
    java-coding-standards.md              — the canonical 912-line rules doc
    faqs/                                 — shared FAQs the FAQ server bundles
        building/java-formatting-standards.md
        building/javadoc-reflow-conventions.md
        conventions/adding-new-faqs.md
        testing/system-stubs-and-output-capture.md

tooling/
    ide/java-formatter.xml                — Eclipse JDT formatter profile
                                             consumed by redhat.java
                                             via java.format.settings.url
    scripts/                              — bulk-format Python scripts
        _cli.py                           — shared argparse + iter helpers
        fix_allman_braces.py
        fix_javadoc_reflow.py
        fix_javadoc_inline_tags.py
        fix_javadoc_tags.py
        fix_need_braces.py
        format_file.py                    — orchestrator (single-file mode
                                             for VSCode keybinding,
                                             PostToolUse hook, etc.)

mcp/
    faq_server.py                         — generic FAQ MCP server, invoked
                                             by consumer projects via uv
                                             with PEP 723 inline metadata

adoption/
    ADOPTION.md                            — human-readable adoption guide
    adopt-standards-prompt.md              — master Claude Code prompt
    slash-commands/init-java.md            — installed in consumer projects
                                              as .claude/commands/init-java.md
    claude-md-templates/                   — drop-in pom / mcp / vscode /
                                              claude-hooks templates
    verification-checklist.md              — post-adoption gates

SECURITY.md                                — maintained invariants for
                                              contributors
README.md                                  — this file

How a consumer adopts this

# In the consumer project:
cd <project-root>
git submodule add \
  https://github.com/senzing-garage/java-coding-standards.git \
  .java-coding-standards
git submodule update --init

Then, in a Claude Code session against the project:

@.java-coding-standards/adoption/adopt-standards-prompt.md run this

Claude walks the adoption flow end to end — pom updates, MCP server entry, VSCode integration, Claude Code hooks, CLAUDE.md merge, generated-file exclusion prompt, optional starter-FAQ generation, verification gates. Re-run later as /init-java (the slash command gets installed by the first run) any time you want to refresh after a submodule pin bump.

See adoption/ADOPTION.md for the full guide, including the manual (non-Claude) path.

Distribution philosophy

Pure git submodule, no published artifacts. The standards repo is the single source of truth for rules, configs, docs, and tooling. A single SHA pin in a consumer's .gitmodules selects exactly which version of all of those a project is on — no skew between "checkstyle.xml v1" and "FAQ corpus v2" because they ship as one submodule snapshot.

CI workflows are out of scope and stay with senzing-factory/build-resources. The standards repo only provides the config files those workflows already consume.

Contributing

Improvements to the standards, scripts, FAQs, or templates are welcome. PRs go to the main branch and require:

• Branch protection: no direct pushes; reviewer approval required.
• Signed commits.
• The maintained invariants in SECURITY.md continue to hold.

When updating a shared FAQ, keep it project-agnostic (no real class names, file paths, or identifiers from any one consumer — use synthetic placeholders).

Versioning

Tags follow semver. Pre-1.0 (v0.x.y) the API surface is still stabilizing — minor versions may carry meaningful behavioral changes to scripts and templates. Once a v1.0.0 is cut, semver guarantees apply normally.

Consumer projects pin to a tag SHA. Bumps are submitted as PRs in consumer projects so the diff is visible to reviewers and never silently rolled in CI.

License

Apache 2.0 (matches the consumer projects).