Skip to content

Add AGENTS.md #1026

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

Merged
michelebastione merged 3 commits into from
Oct 15, 2026
Merged

Add AGENTS.md #1026

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
e4f47e2
Add AGENTS.md
virzak Oct 14, 2026
26d14ca
Quote the AI usage policy as CONTRIBUTING.md words it
virzak Oct 14, 2026
c611f3f
Say which benchmarks a MiniExcel filter selects
virzak Oct 14, 2026
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
32 changes: 32 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,32 @@
# AGENTS.md

Notes for coding agents and new contributors. [CONTRIBUTING.md](CONTRIBUTING.md) still applies, including its AI usage policy: agents may be used for bugfixes, unit tests and documentation, not for new features.

## Layout

- `src/MiniExcel.Core`, `src/MiniExcel.OpenXml`, `src/MiniExcel.Csv`: the v2 library. The entry point is `MiniExcelV2` (exporters, importers, templaters, editors).
- `src/MiniExcel.OpenXml.FluentMapping`: the mapping importer and exporter.
- `src/MiniExcel`: the `MiniExcel` package, a facade that keeps the v1 static API working on top of v2.
- `tests/MiniExcel.OpenXml.Tests`, `tests/MiniExcel.Csv.Tests`: xUnit tests.
- `benchmarks/MiniExcel.Benchmarks`: BenchmarkDotNet benchmarks.

## Code

- Sync methods are generated by Zomp.SyncMethodGenerator from async methods marked `[CreateSyncVersion]`. Edit only the async method; the sync version is regenerated on build.
- Reading and writing run per cell, so code on those paths should not allocate per call (LINQ closures, substrings, interpolated strings) or take locks.
- The libraries target `netstandard2.0` as well as current .NET, so APIs that only exist in newer frameworks need a fallback or `#if NET`.

## Build and test

- Tests run on net8.0 through net11.0: `dotnet test tests/MiniExcel.OpenXml.Tests` and `dotnet test tests/MiniExcel.Csv.Tests`. A change should pass on all of them.
- Every PR needs an issue and should add tests for its change.

## Benchmarks

- Query, create and template benchmarks are in `benchmarks/MiniExcel.Benchmarks/BenchmarkSections`. Performance changes should show before and after numbers from these, run on the same machine.
- Select methods with a filter that includes the class name, e.g. `--filter '*QueryExcelBenchmark.MiniExcel*'`. The namespace contains "MiniExcel", so `*MiniExcel*` alone runs every benchmark registered in `Program.cs`.
- The configured job is a short run (3 iterations), which is enough for large differences. For changes of around 10%, add `--iterationCount 15 --launchCount 3`.

## Documentation

- v2 usage is documented in `README_V2.md`. A new feature adds a numbered section there.
Loading