Authoritative guide for AI-assisted work on this repository. Keep this file updated as new decisions are made.

XChart is a lightweight Java charting library (org.knowm.xchart). Current version: 4.0.0-SNAPSHOT | Java target: 11 | Build: Maven ≥ 3.9.0

xchart/          ← core library (the only deliverable jar)
xchart-demo/     ← standalone demo app; references xchart as a dep

Every chart type Foo requires this exact set of classes:

Render style enums live inside the series class (e.g. CategorySeries.CategorySeriesRenderStyle).

Series (abstract)
  └─ AxesChartSeries (abstract) – has xMin/xMax/yMin/yMax, stroke, lineColor
       ├─ AxesChartSeriesNumericalNoErrorBars
       └─ AxesChartSeriesCategory – adds xData, yData, errorBars
            └─ CategorySeries, HeatMapSeries, …
  └─ (direct) PieSeries, DialSeries, RadarSeries, …

• Series.DataType enum: Number, Date, String
• calculateMinMax() must be called whenever series data changes

// 1. plain size
public FooChart(int width, int height) {
    super(width, height, new FooStyler());
    axisPair = new AxisPair<>(this);   // omit for non-axes charts (Pie, Dial, Radar)
    plot     = new Plot_Foo<>(this);
    legend   = new Legend_Foo<>(this);
}

// 2. custom Theme instance
public FooChart(int width, int height, Theme theme) {
    this(width, height);
    styler.setTheme(theme);
}

// 3. ChartTheme enum
public FooChart(int width, int height, ChartTheme chartTheme) {
    this(width, height, chartTheme.newInstance(chartTheme));
}

// 4. Builder (always delegates to #3)
public FooChart(FooChartBuilder chartBuilder) {
    this(chartBuilder.width, chartBuilder.height, chartBuilder.chartTheme);
    setTitle(chartBuilder.title);
    // set axis titles etc. from builder fields
}

// Field (private, initialized in setAllStyles())
private SomeType fieldName;

// Getter — blank line before return
public SomeType getFieldName() {

  return fieldName;
}

// Setter — Javadoc with @param, fluent return this
/**
 * One-sentence description.
 *
 * @param fieldName description
 */
public FooStyler setFieldName(SomeType fieldName) {

  this.fieldName = fieldName;
  return this;
}

• All fields must be initialized in setAllStyles(), pulling values from theme where applicable.
• setAllStyles() must call super.setAllStyles() first.
• Never add state to the base Styler class unless it truly applies to every chart type.

• Formatter: fmt-maven-plugin (google-java-format).
• Check only: mvn fmt:check (used in CI). Run this to detect violations.
• NEVER run mvn fmt:format project-wide. It reformats every file, pollutes diffs, and causes merge conflicts across all open branches. If a PR has violations, ask the contributor to run mvn fmt:format on their own changed files only and push a fix commit.
• Indentation: 2 spaces (google style).
• Imports: sorted by google-java-format; no wildcard imports in src/main. Tests may use import static … Assertions.*.
• One blank line between class members; blank line before return in getters.
• Always end files with a newline character.

# Full build + tests
mvn clean verify

# Format source
mvn fmt:format

# Tests only
mvn test -pl xchart

# Skip tests
mvn install -DskipTests

xchart-demo depends on xchart via the local Maven repository (not the source tree). You must install xchart first, then run the demo:

mvn install -pl xchart -DskipTests && \
mvn compile exec:java \
  -pl xchart-demo \
  -Dexec.mainClass="org.knowm.xchart.standalone.issues.TestForIssueXXX"

Using just exec:java without the install step will run with a stale jar and changes won't be visible.

Tests use JUnit Jupiter 5 + AssertJ.

@BeforeEach
void setUp() { chart = new FooChart(800, 600, GGPlot2); }

@Test
void descriptiveCamelCaseNameNoTestPrefix() {
    assertAll(
        () -> assertDoesNotThrow(...),
        () -> assertThat(series.getName()).isEqualTo("expected")
    );
}

// Exception testing
assertThatThrownBy(() -> { ... })
    .isInstanceOf(IllegalArgumentException.class)
    .hasMessageMatching("Series name >x< ...");

• Tests go in xchart/src/test/java/org/knowm/xchart/ mirroring the main package.
• One test class per chart type or internal component.
• New public API must include tests.

Changes in these files affect every chart type — review with extra care:

Any PR touching these files should be tested by painting multiple chart types, not just the one the PR targets.

Every code PR should be accompanied by a standalone runnable demo that exercises the fix or feature.

package org.knowm.xchart.standalone.prs; // or .issues

public class TestForPRXXX {

  public static void main(String[] args) {
    new SwingWrapper<>(getChart()).displayChart();
  }

  /** Constructs and returns the chart without launching a window (headless-safe). */
  public static FooChart getChart() {
    // build and return chart
  }
}

• getChart() must be public static so it can be called from unit tests without a display.
• No Swing/AWT calls outside of main().
• Separate getChartXxx() methods when demonstrating multiple variants of the same feature.

When evaluating a PR, rank it higher if it:

1. Passes mvn fmt:check (no formatting violations).
2. Follows the exact naming conventions above.
3. Adds or updates tests for new/changed behaviour.
4. Targets only the chart type it claims to change (no incidental changes to base classes).
5. Is free of wildcard imports in src/main.
6. Has a \n at the end of every changed file.
7. Does not set sibling state as a side-effect of a setter (e.g. a setter for field A silently nulling field B is fragile).
8. Uses the existing seriesMap (LinkedHashMap — insertion order is meaningful) iteration patterns.

Lower-risk PRs: single-field styler additions, dependency bumps with passing CI. Higher-risk PRs: new chart types, changes to rendering base classes, refactors of Utils/CSVImporter.

Last updated: 2026-05-17