From e4f47e2ebec1bfca284000b9c0ede50de88a1669 Mon Sep 17 00:00:00 2001 From: Victor Irzak Date: Wed, 14 Oct 2026 10:26:22 -0400 Subject: [PATCH 1/3] Add AGENTS.md --- AGENTS.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..0b92bd46 --- /dev/null +++ b/AGENTS.md @@ -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 bug fixes, 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. +- 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. From 26d14ca80d010733818e972e9c0fcbee1a3890d7 Mon Sep 17 00:00:00 2001 From: Victor Irzak Date: Wed, 14 Oct 2026 10:52:31 -0400 Subject: [PATCH 2/3] Quote the AI usage policy as CONTRIBUTING.md words it --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 0b92bd46..6704473c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # 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 bug fixes, tests and documentation, not for new features. +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 From c611f3fd53fbf283e38efb53b7fa14740ba48036 Mon Sep 17 00:00:00 2001 From: Victor Irzak Date: Wed, 14 Oct 2026 11:35:14 -0400 Subject: [PATCH 3/3] Say which benchmarks a MiniExcel filter selects --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6704473c..0a41c24f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -24,7 +24,7 @@ Notes for coding agents and new contributors. [CONTRIBUTING.md](CONTRIBUTING.md) ## 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. +- 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