The code is formatted with the MetricsHub Eclipse formatter profile (metricshub-eclipse-formatter.xml, byte-identical to jawk's): tabs, 120-column lines. formatter:validate runs at the validate phase, so unformatted code fails the build. Simply run mvn formatter:format before committing, and do not hand-format code.
Checkstyle (checkstyle.xml, byte-identical to jawk's) runs at verify with failOnViolation=true. Fix violations rather than suppressing them; when a suppression is justified, wrap the code in // CHECKSTYLE.OFF: <RuleName> / // CHECKSTYLE.ON: <RuleName> comments.
All Java source files under src/main/java must include the proper LGPL-3 license header (the license-maven-plugin check covers main/java/**/*.java only; tests, Markdown and resources carry no header). When you add a new source file, run mvn license:update-file-header before committing (and before building, since the build fails if a source file lacks the header). The plugin only adds missing headers; it is configured never to rewrite existing ones, so do not edit copyright lines in bulk. The library is a fork of the Verax Systems IPMI Library for Java: files derived from Verax code (org.metricshub.ipmi.core) say Copyright 2023 Verax Systems, MetricsHub, files written by MetricsHub say Copyright 2023 MetricsHub. A new file gets a MetricsHub copyright line; if it contains code moved from a Verax-derived file, give it that file's copyright line.
All public methods must have proper Javadoc. Check the output of Maven to identify issues with Javadoc and fix these issues.
The library targets Java 8 (maven.compiler.release is 8): no var, records, switch expressions, text blocks or APIs newer than Java 8 in src/main.
The project uses Maven to build. A full build is performed with mvn verify site (or mvn clean verify site when applicable). CI runs the same on JDK 17.
@codex, please don't try to use mvnw (Maven Wrapper). Maven is already installed and runs perfectly well.
Whenever required, when you add code or when you modify code that is not covered with unit tests, add the corresponding unit tests. All tests must pass with mvn test. Don't use the -q (silent) option, as you want to see the result of successful tests. Tests are run with the Maven surefire plugin and results are stored in the ./target/surefire-reports directory.
Unit tests must not depend on a real BMC. Exercising the RMCP+ session code against real hardware is done with throw-away harnesses outside the repository; never commit hostnames, user names or passwords of test systems. When testing against a real BMC, keep in mind that BMCs drop UDP replies under concurrent sessions: repeat a failing request before blaming the library, set a short per-message timeout with IpmiConnector.setTimeout(handle, ms), and end harness main methods with System.exit(0) because the library leaves non-daemon threads behind after a timeout.
Code quality reports (checkstyle, pmd/cpd, spotbugs) are generated by mvn verify site into ./target/checkstyle-result.xml, ./target/pmd.xml, ./target/cpd.xml and ./target/spotbugsXml.xml. Checkstyle and PMD are gated (the build fails on any error); CPD is gated on duplications of 100 tokens or more (cpd-check at verify), while the site report lists those of 50 tokens or more; SpotBugs is gated on any bug at the default threshold (spotbugs:check at verify). Extract shared code instead of copying it: AbstractSensorRecord holds what the Full, Compact and Event-Only sensor records share, and IpmiCommandCoder.validateResponse() the response checks of every command. Do not add new violations: check the reports for the files you changed before committing and submitting your code. The SpotBugs gate and site report run spotbugs-maven-plugin 4.10.4.1 (pinned in <build> and <reporting>, as the 4.9.3.0 of the parent POM cannot read the class files of JDK 21+); to run SpotBugs alone, use mvn com.github.spotbugs:spotbugs-maven-plugin:4.10.4.1:check. Fix SpotBugs findings; when one is intentional, suppress it with @SuppressFBWarnings (spotbugs-annotations, provided scope) and a justification. CT_CONSTRUCTOR_THROW and EI_EXPOSE_REP (which also matches EI_EXPOSE_REP2) are suppressed for the whole protocol core in org/metricshub/ipmi/core/package-info.java; SpotBugs reports a suppression that matches nothing, so remove it with the code it covered.
Always make sure that public API changes are properly documented in src/site/markdown/*.md and that README.md is always up-to-date. The published documentation is https://metricshub.org/ipmi-java.
The site is built with maven-site-plugin 4 and the Sentry Maven Skin (https://sentrysoftware.org/sentry-maven-skin/, see its "Vibe Writing" page for the syntax: callouts, tabs, toc macro). Every page starts with keywords: and description: headers, has a single H1 and the toc macro, and is listed in src/site/site.xml (Getting Started, Usage or Reference menu). Keep the pages true to the code: verify examples against the API (and, where they show output, against a real BMC). File the library bugs found while writing documentation as GitHub issues instead of describing them in the pages, which document how the library is meant to work. User-visible changes go to upgrading.md.
- The protocol implementation lives in
org.metricshub.ipmi.core(RMCP+, RAKP, SDR/FRU/SEL coders, connection state machine); the MetricsHub-facing API isorg.metricshub.ipmi.client(IpmiClient,IpmiClientConfiguration, the runners andIpmiResultConverter). - Decoders must never abort a whole SDR repository walk or FRU decode on a record they do not model: skip, log and continue (IPMI 2.0 reserves SDR record types 0xC0-0xFF for OEM use and vendors do emit them).
- Byte-level parsing must follow the IPMI 2.0 specification (section numbers are cited in the code and in the issues); when a finding is "by the spec" but not reproduced on real hardware, say so in the commit or PR.