From 0bed20504c98db38d96913df3f8fc9f85de66d2e Mon Sep 17 00:00:00 2001 From: Jochen Wezel Date: Tue, 5 May 2026 17:54:33 +0200 Subject: [PATCH] Add agent guidance and encoding rules --- .editorconfig | 5 +++++ .gitattributes | 18 +++++++++++++++++- AGENTS.md | 37 +++++++++++++++++++++++++++++++++++++ 3 files changed, 59 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md diff --git a/.editorconfig b/.editorconfig index 129fabe..d4c8ee8 100644 --- a/.editorconfig +++ b/.editorconfig @@ -2,3 +2,8 @@ # S1135: Track uses of "TODO" tags dotnet_diagnostic.S1135.severity = suggestion +# Text file defaults for this repository +[*] +charset = utf-8-bom +end_of_line = crlf +insert_final_newline = true diff --git a/.gitattributes b/.gitattributes index 38e7829..f302cff 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,4 +1,20 @@ -*/_CreateNewNuGetPackage/* linguist-vendored +*/_CreateNewNuGetPackage/* linguist-vendored NDoc/* linguist-vendored *.cmd linguist-vendored *.ps1 linguist-vendored +* text=auto eol=crlf +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.zip binary +*.nupkg binary +*.snk binary +*.pfx binary +*.xls binary +*.xlsx binary +*.doc binary +*.docx binary +*.ppt binary +*.pptx binary diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dab5e4f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,37 @@ +# Repository Guidance for Agents + +## Communication + +- Write all GitHub issue comments, pull request comments, pull request descriptions, commit messages, and other GitHub-facing text in English. +- Keep user-facing explanations in the language used by the user unless asked otherwise. + +## Public and Protected API + +- Preserve binary/source compatibility whenever possible. Do not remove or rename public members without an explicit request. +- When replacing an existing public member, keep the old member as an obsolete wrapper and delegate to the new implementation with the previous default behavior. +- Keep API wording consistent with existing naming. For example, prefer existing `Remove...` terminology over introducing `Delete...` for the same conceptual operation. +- Avoid unrelated API changes or side features while implementing a requested feature. + +## XML Documentation + +- Every new public API member must have XML documentation matching the quality of the surrounding API. +- Public enums and their values must be documented. +- Keep `` text short and focused, for example `Insert one or more columns.`. +- For new or substantially edited XML documentation, prefer Microsoft-style complete sentences in descriptive third-person form with a final period, for example `Inserts one or more columns.`. +- Treat broad cleanup of older XML documentation style as a separate follow-up task instead of mixing it into feature or targeted documentation commits. +- Put details such as zero-based indexing, insertion position, behavior contracts, and parameter semantics into ``, ``, ``, or `` elements as appropriate. +- Prefer simple grammar that is easy to understand for non-native English speakers. +- For overrides, always add an explicit `` when the inherited documentation applies. Do not rely on implicit inherited documentation from an undocumented override. +- For overloads with mostly identical documentation, prefer `` plus targeted ``, ``, ``, or `` overrides instead of copying large documentation blocks. +- Add `` to inherited documentation only for specific behavior or limitations. + +## Tests and Generated Files + +- Add durable unit tests for new behavior. +- Test methods should preferably include short comments or XML summaries explaining why the test exists and what workbook behavior it verifies, but this is guidance and not a mandatory API documentation requirement. + +## File Encoding and Line Endings + +- Save text files as UTF-8 with BOM and CRLF line endings, matching `.editorconfig`. +- Keep `.gitattributes` line-ending rules intact and mark binary workbook/image/archive formats as binary. +- When normalizing encoding or line endings, keep that work in a separate mechanical commit whenever possible.