Skip to content

Adopt code-review profile, align contributor policy to ISO-8859-1, harden test utilities, and tidy docs #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
peter-lawrey wants to merge 10 commits into
base: develop
Choose a base branch
from
Draft

Adopt code-review profile, align contributor policy to ISO-8859-1, harden test utilities, and tidy docs #136

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
e574211
Add code-review profile scaffolding
peter-lawrey Oct 28, 2025
fa9d530
Scope JaCoCo to code-review profile
peter-lawrey Oct 28, 2025
13c2993
Pin SpotBugs tooling to 4.8.6.6
peter-lawrey Oct 28, 2025
e06b857
Update copyright information to reflect current ownership
peter-lawrey Oct 28, 2025
66cc6af
Tighten JaCoCo coverage gates
peter-lawrey Oct 28, 2025
aaa9d0d
Address SpotBugs and PMD findings
peter-lawrey Oct 28, 2025
54557de
Make proxy ByteBuffer operations Java-8 compatible
peter-lawrey Oct 28, 2025
7db78fd
Refactor SpotBugs exclusions and remove deprecated @SuppressFBWarning…
peter-lawrey Oct 29, 2025
b1dbba0
Remove unused SpotBugs annotations dependency from pom.xml
peter-lawrey Oct 29, 2025
0071200
Move Checkstyle config under src/main/config
peter-lawrey Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ LLM-based agents can accelerate development only if they respect our house rules
| Requirement | Rationale |
|--------------|-----------|
| **British English** spelling (`organisation`, `licence`, *not* `organization`, `license`) except technical US spellings like `synchronized` | Keeps wording consistent with Chronicle's London HQ and existing docs. See the University of Oxford style guide for reference. |
| **ASCII-7 only** (code-points 0-127). Avoid smart quotes, non-breaking spaces and accented characters. | ASCII-7 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
| If you must show a symbol that does not exist in ASCII-7, spell it out (`micro-second`, `>=`, `:alpha:`, `:yes:`) rather than inserting Unicode. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |
| **ISO-8859-1** (code-points 0-255). Avoid smart quotes, non-breaking spaces and accented characters. | ISO-8859-1 survives every toolchain Chronicle uses, incl. low-latency binary wire formats that expect the 8th bit to be 0. |
| If you must show a symbol that does not exist in ISO-8859-1, spell it out (`micro-second`, `>=`, `:alpha:`, `:yes:`) rather than inserting Unicode. | Extended or '8-bit ASCII' variants are *not* portable and are therefore disallowed. |

## Javadoc guidelines

Expand Down Expand Up @@ -52,8 +52,8 @@ mvn -q verify

## Project requirements

See the [Decision Log](src/main/adoc/decision-log.adoc) for the latest project decisions.
See the [Project Requirements](src/main/adoc/project-requirements.adoc) for details on project requirements.
See the [Decision Log](src/main/docs/decision-log.adoc) for the latest project decisions.
See the [Project Requirements](src/main/docs/project-requirements.adoc) for details on project requirements.

## Elevating the Workflow with Real-Time Documentation

Expand Down Expand Up @@ -85,7 +85,7 @@ This tight loop informs the AI accurately and creates immediate clarity for all

When using AI agents to assist with development, please adhere to the following guidelines:

* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ASCII-7 guidelines outlined above.
* **Respect the Language & Character-set Policy**: Ensure all AI-generated content follows the British English and ISO-8859-1 guidelines outlined above.
Focus on Clarity: AI-generated documentation should be clear and concise and add value beyond what is already present in the code or existing documentation.
* **Avoid Redundancy**: Do not generate content that duplicates existing documentation or code comments unless it provides additional context or clarification.
* **Review AI Outputs**: Always review AI-generated content for accuracy, relevance, and adherence to the project's documentation standards before committing it to the repository.
Expand Down Expand Up @@ -159,4 +159,4 @@ Do not rely on indentation for list items in AsciiDoc documents. Use the followi

### Emphasis and Bold Text

In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
In AsciiDoc, an underscore `_` is _emphasis_; `*text*` is *bold*.
31 changes: 24 additions & 7 deletions README.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

image:https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-test-framework/badge.svg[Maven Central,link=https://maven-badges.herokuapp.com/maven-central/net.openhft/chronicle-test-framework]
image:https://javadoc.io/badge2/net.openhft/chronicle-test-framework/javadoc.svg[Javadoc,link="https://www.javadoc.io/doc/net.openhft/chronicle-test-framework/latest/index.html"]
//image:https://javadoc-badge.appspot.com/net.openhft/chronicle-test-framework.svg?label=javadoc[JavaDoc, link=https://www.javadoc.io/doc/net.openhft/chronicle-test-framework]
// image:https://javadoc-badge.appspot.com/net.openhft/chronicle-test-framework.svg?label=javadoc[JavaDoc, link=https://www.javadoc.io/doc/net.openhft/chronicle-test-framework]
image:https://img.shields.io/github/license/OpenHFT/Chronicle-Test-Framework[Licence]
image:https://img.shields.io/badge/release%20notes-subscribe-brightgreen[Release Notes,link="https://chronicle.software/release-notes/"]
image:https://sonarcloud.io/api/project_badges/measure?project=OpenHFT_ChronicleTestFramework&metric=alert_status[Quality Gate,link="https://sonarcloud.io/dashboard?id=OpenHFT_Chronicle-Test-Framework"]
Expand All @@ -18,6 +18,17 @@ toc::[]

Chronicle Test Framework provides test-data generators and API metrics tools for JUnit 4 and JUnit 5. Use the combinators to create permutations, combinations and products, or analyse your packages with the metrics builder.

== Quality Checks

Activate the `code-review` Maven profile before sending patches:

[source,bash]
----
mvn -q -Pcode-review verify
----

The profile runs Checkstyle, SpotBugs, PMD, and JaCoCo with the shared Chronicle rules to catch regressions early.

== Permutations

Permutations work like this:
Expand Down Expand Up @@ -69,7 +80,8 @@ Stream<DynamicTest> demo() {
== API Metrics Builder

The API metrics feature analyses the public and internal surface of your
packages. Create the builder via `ApiMetrics.builder()` then supply the
packages.
Create the builder via `ApiMetrics.builder()` then supply the
packages to scan, the metrics to apply and the accumulators that gather the
results.

Expand All @@ -82,9 +94,12 @@ ApiMetrics metrics = ApiMetrics.builder()
.build();
----

The builder applies no defaults. If you omit metrics or accumulators the
result will be empty. Default metrics and accumulators are only added when you
call the relevant `addStandard` methods. Packages with `.internal.` in the
The builder applies no defaults.
If you omit metrics or accumulators the
result will be empty.
Default metrics and accumulators are only added when you
call the relevant `addStandard` methods.
Packages with `.internal.` in the
name, or those ending in `.internal`, are collected in a separate internal
group.

Expand Down Expand Up @@ -231,7 +246,8 @@ Stream<DynamicTest> demo() {

== API Metrics Accumulators

The framework includes a small set of predefined accumulator suppliers used by the API metrics analysis. They help to group metric counts in common ways.
The framework includes a small set of predefined accumulator suppliers used by the API metrics analysis.
They help to group metric counts in common ways.

* `perMethod()` groups by the full method signature so that overloaded methods are reported separately.
* `perClassAndMetric()` groups first by class and then by metric, giving a table of metric totals for each class.
Expand All @@ -240,4 +256,5 @@ The framework includes a small set of predefined accumulator suppliers used by t
* `PER_PACKAGE` reports a single total for each package.
* `PER_METHOD_REFERENCE` groups by method name only, ignoring parameter types, so all overloads are counted as one.

The convenience factories in `Accumulator` expose the first two suppliers for general use. The others are mainly for internal analyses but may be reused when custom behaviour is needed.
The convenience factories in `Accumulator` expose the first two suppliers for general use.
The others are mainly for internal analyses but may be reused when custom behaviour is needed.
172 changes: 153 additions & 19 deletions pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,15 @@
<properties>
<sonar.organization>openhft</sonar.organization>
<sonar.host.url>https://sonarcloud.io</sonar.host.url>
<checkstyle.version>3.6.0</checkstyle.version>
<puppycrawl.version>8.45.1</puppycrawl.version>
<spotbugs.version>4.8.6.6</spotbugs.version>
<findsecbugs.version>1.14.0</findsecbugs.version>
<maven-pmd-plugin.version>3.28.0</maven-pmd-plugin.version>
<jacoco-maven-plugin.version>0.8.14</jacoco-maven-plugin.version>
<jacoco.line.coverage>0.846</jacoco.line.coverage>
<jacoco.branch.coverage>0.707</jacoco.branch.coverage>
<chronicle-quality-rules.version>1.23ea6</chronicle-quality-rules.version>
</properties>

<dependencyManagement>
Expand Down Expand Up @@ -119,25 +128,6 @@
</plugin>


<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<executions>
<execution>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>report</id>
<phase>prepare-package</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
</executions>
</plugin>

<plugin>
<groupId>org.sonarsource.scanner.maven</groupId>
<artifactId>sonar-maven-plugin</artifactId>
Expand All @@ -146,6 +136,150 @@
</plugins>
</build>

<profiles>
<profile>
<id>code-review</id>
<activation>
<activeByDefault>false</activeByDefault>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-checkstyle-plugin</artifactId>
<version>${checkstyle.version}</version>
<dependencies>
<dependency>
<groupId>com.puppycrawl.tools</groupId>
<artifactId>checkstyle</artifactId>
<version>${puppycrawl.version}</version>
</dependency>
<dependency>
<groupId>net.openhft</groupId>
<artifactId>chronicle-quality-rules</artifactId>
<version>${chronicle-quality-rules.version}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>checkstyle</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
<configuration>
<configLocation>src/main/config/checkstyle.xml</configLocation>
<consoleOutput>true</consoleOutput>
<failOnViolation>true</failOnViolation>
<violationSeverity>warning</violationSeverity>
</configuration>
</plugin>
<plugin>
<groupId>com.github.spotbugs</groupId>
<artifactId>spotbugs-maven-plugin</artifactId>
<version>${spotbugs.version}</version>
<dependencies>
<dependency>
<groupId>com.h3xstream.findsecbugs</groupId>
<artifactId>findsecbugs-plugin</artifactId>
<version>${findsecbugs.version}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>spotbugs</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
<configuration>
<effort>Max</effort>
<threshold>Low</threshold>
<failOnError>true</failOnError>
<excludeFilterFile>src/main/config/spotbugs-exclude.xml</excludeFilterFile>
<plugins>
<plugin>
<groupId>com.h3xstream.findsecbugs</groupId>
<artifactId>findsecbugs-plugin</artifactId>
<version>${findsecbugs.version}</version>
</plugin>
</plugins>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-pmd-plugin</artifactId>
<version>${maven-pmd-plugin.version}</version>
<executions>
<execution>
<id>pmd</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
</execution>
</executions>
<configuration>
<failOnViolation>true</failOnViolation>
<printFailingErrors>true</printFailingErrors>
<excludeFromFailureFile>src/main/config/pmd-exclude.properties</excludeFromFailureFile>
</configuration>
</plugin>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>${jacoco-maven-plugin.version}</version>
<executions>
<execution>
<id>prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>report</id>
<phase>verify</phase>
<goals>
<goal>report</goal>
</goals>
</execution>
<execution>
<id>check</id>
<phase>verify</phase>
<goals>
<goal>check</goal>
</goals>
<configuration>
<rules>
<rule>
<element>BUNDLE</element>
<limits>
<limit>
<counter>LINE</counter>
<value>COVEREDRATIO</value>
<minimum>${jacoco.line.coverage}</minimum>
</limit>
<limit>
<counter>BRANCH</counter>
<value>COVEREDRATIO</value>
<minimum>${jacoco.branch.coverage}</minimum>
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>

<repositories>
<repository>
<id>chronicle-enterprise-snapshots</id>
Expand Down
Loading