Skip to content

Commit a4949f1

Browse files
kMutagenekMutagene
committed
add agents.md
1 parent c13d887 commit a4949f1

1 file changed

Lines changed: 118 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# AGENTS.md
2+
3+
Guidance for AI coding agents working in the Plotly.NET repo. This is a first draft — please update it as conventions evolve.
4+
5+
## What this repo is
6+
7+
Plotly.NET is an interactive charting library for .NET, built on top of plotly.js. The core is written in F# and wraps the plotly.js JSON schema with multiple API layers (high-level type-safe `Chart` API down to low-level object manipulation). See [README.md](README.md) for user-facing docs and the [F1000Research paper](https://doi.org/10.12688/f1000research.123971.1) for design rationale.
8+
9+
Currently targeted plotly.js version: **2.27.1** (bundled at [src/Plotly.NET/plotly-2.27.1.min.js](src/Plotly.NET/plotly-2.27.1.min.js)).
10+
11+
## Packages (monorepo layout)
12+
13+
All shipped packages live under [src/](src/):
14+
15+
- **[Plotly.NET](src/Plotly.NET/)** — core F# library. Everything else depends on this.
16+
- **[Plotly.NET.CSharp](src/Plotly.NET.CSharp/)** — idiomatic C# wrapper around the core API.
17+
- **[Plotly.NET.Interactive](src/Plotly.NET.Interactive/)** — formatter extensions for .NET Interactive / Polyglot Notebooks.
18+
- **[Plotly.NET.ImageExport](src/Plotly.NET.ImageExport/)** — static image (PNG/SVG/JPEG/PDF) rendering.
19+
- **[Plotly.NET.Verso](src/Plotly.NET.Verso/)** — Verso integration.
20+
21+
Inside [src/Plotly.NET/](src/Plotly.NET/), the core is organized by concern:
22+
23+
- [ChartAPI/](src/Plotly.NET/ChartAPI/) — high-level `Chart` API (`Chart2D`, `Chart3D`, `ChartMap`, `ChartPolar`, etc.) and `GenericChart`.
24+
- [Traces/](src/Plotly.NET/Traces/) — trace types (`Trace2D`, `Trace3D`, `TraceGeo`, …) matching plotly.js trace categories.
25+
- [Layout/](src/Plotly.NET/Layout/) — layout objects (axes, legends, annotations, shapes, …).
26+
- [CommonAbstractions/](src/Plotly.NET/CommonAbstractions/) — shared enums, style objects, and types used across traces/layouts.
27+
- [Config/](src/Plotly.NET/Config/), [DisplayOptions/](src/Plotly.NET/DisplayOptions/), [Templates/](src/Plotly.NET/Templates/) — render-time configuration.
28+
- [Globals.fs](src/Plotly.NET/Globals.fs), [Defaults.fs](src/Plotly.NET/Defaults.fs), [InternalUtils.fs](src/Plotly.NET/InternalUtils.fs) — globals and helpers.
29+
30+
## Build system — use FAKE, not `dotnet build` directly
31+
32+
The build is a FAKE script defined as an executable F# project at [build/build.fsproj](build/build.fsproj). It controls project ordering, version injection from `RELEASE_NOTES.md`, packing, and test execution. **Do not use `dotnet build` directly** — always go through the build project:
33+
34+
```shell
35+
# Windows
36+
./build.cmd # default target: Build
37+
./build.cmd runTestsCore # run a specific target
38+
39+
# Linux / macOS
40+
./build.sh
41+
./build.sh runTestsAll
42+
43+
# Or invoke the build project directly
44+
dotnet run --project ./build/build.fsproj
45+
dotnet run --project ./build/build.fsproj -- RunTestsExtensionLibs
46+
```
47+
48+
Key build files:
49+
50+
- [build/ProjectInfo.fs](build/ProjectInfo.fs) — registry of all projects (library + test). **New projects must be added here**, both in the `projects` list and in the relevant test-project lists.
51+
- [build/Build.fs](build/Build.fs) — main build targets, `sourceFiles` glob. New projects may also need to be registered in the glob.
52+
- [build/TestTasks.fs](build/TestTasks.fs) — test build and run targets (see below).
53+
- [build/PackageTasks.fs](build/PackageTasks.fs), [build/ReleaseTasks.fs](build/ReleaseTasks.fs) — pack and release pipeline.
54+
- [build/DocumentationTasks.fs](build/DocumentationTasks.fs) — docs build targets.
55+
56+
Every shipped project needs its own `RELEASE_NOTES.md` — the build parses the top entry to derive the package version and assembly version.
57+
58+
## Tests
59+
60+
See [tests/README.md](tests/README.md) for the authoritative overview. Short version:
61+
62+
### Frameworks
63+
- F# test projects: **Expecto** (majority) or xUnit.
64+
- C# test projects: **xUnit**.
65+
- JS test projects: **Mocha** (run in node; primarily validate generated JSON against `Plotly.validate`).
66+
67+
### Layout ([tests/](tests/))
68+
- [Common/](tests/Common/) — `FSharpTestBase` and `CSharpTestBase` class libraries containing shared `TestUtils`, `TestCharts`, and helpers (`substringIsInChart`, `chartGeneratedContains`, `getFullPlotlyJS`, …). Test projects reference these.
69+
- [CoreTests/](tests/CoreTests/) — largest suite. Tests HTML generation, JSON serialization, object validity for the core `Plotly.NET` library. Includes `CoreTests.fsproj` and `CSharpInteroperabilityTests.csproj`.
70+
- [ExtensionLibsTests/](tests/ExtensionLibsTests/) — tests for `Plotly.NET.CSharp`, `Plotly.NET.ImageExport`, etc.
71+
- [InteractiveTests/](tests/InteractiveTests/) — tests for `Plotly.NET.Interactive`.
72+
- [JSTests/](tests/JSTests/) — node/Mocha tests validating generated JSON with plotly.js.
73+
- [VersoTests/](tests/VersoTests/) — tests for `Plotly.NET.Verso`.
74+
- [ConsoleApps/](tests/ConsoleApps/) — manual-test playgrounds, not unit tests.
75+
76+
### Running tests
77+
78+
```shell
79+
./build.cmd runTestsAll # everything
80+
./build.cmd runTestsCore # CoreTests
81+
./build.cmd runTestsExtensionLibs # extension lib tests
82+
./build.cmd runTestsJSTests # JS / Mocha tests
83+
```
84+
85+
### Writing tests
86+
- Use `FSharpTestBase` helpers: `substringIsInChart`, `chartGeneratedContains`, `getFullPlotlyJS`, etc.
87+
- **Set `UseDefaults = false` on test charts** to avoid dumping the large default template HTML into test output and making diffs unreadable.
88+
- When overriding `PlotlyJSReference` in tests, prefer `Chart.withDisplayOptions` (full replacement) over `Chart.withDisplayOptionsStyle` (merge) — the merge form doesn't reliably override CDN defaults.
89+
90+
## Docs
91+
92+
Docs live in [docs/](docs/) as `.fsx` and `.md` files, organized by chart family (`3D-charts/`, `categorical-charts/`, `distribution-charts/`, …). They are rendered with FSharp.Formatting. To run a local dev server with hot reload:
93+
94+
```shell
95+
./build.cmd watchdocs # or ./build.sh watchdocs
96+
```
97+
98+
When adding a new chart type or API surface, add or update the corresponding `.fsx` in the appropriate subfolder.
99+
100+
## Adding a new project — checklist
101+
102+
1. Create the project under [src/](src/) or [tests/](tests/).
103+
2. Add a `RELEASE_NOTES.md` at the project root (for shipped projects).
104+
3. Register it in [build/ProjectInfo.fs](build/ProjectInfo.fs) (projects list + any relevant test-project lists).
105+
4. Update the `sourceFiles` glob in [build/Build.fs](build/Build.fs) if needed.
106+
5. Add the project to the appropriate `.sln` ([Plotly.NET.sln](Plotly.NET.sln), [Plotly.NET.Core.sln](Plotly.NET.Core.sln), or [Plotly.NET.TestSuite.sln](Plotly.NET.TestSuite.sln)).
107+
6. Run `./build.cmd` (or `build.sh`) and the relevant test target to verify.
108+
109+
## Conventions and gotchas
110+
111+
- F# file order matters — new `.fs` files must be added to the `.fsproj` in the correct position.
112+
- The core library is designed for C# interop — when adding public API, consider how it looks from C# (see the FAQ in [README.md](README.md) and [issue #285](https://github.com/plotly/Plotly.NET/issues/285)).
113+
- Release targets (`release`, `prerelease`) expect a `NUGET_KEY` environment variable. Don't run these unless you actually intend to publish.
114+
- Main branch for PRs is **`dev`**, not `main`/`master`.
115+
116+
## License
117+
118+
MIT — see [LICENSE](LICENSE).

0 commit comments

Comments
 (0)