CSHARP-5943: Initial small AGENTS.md file for the C# driver #1934
+54
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,53 @@ | ||
| # AGENTS.md - CSharpDriver | ||
|
|
||
| ## Overview | ||
| The C# driver for MongoDB. | ||
|
|
||
| ## Tech Stack | ||
| - .NET library projects producing NuGet packages | ||
| - Multi-targeted to various .NET versions from .NET Framework 4.7.2 up | ||
| - xUnit + FluentAssertions for testing | ||
|
|
||
| ## Project Structure | ||
|
Contributor
There was a problem hiding this comment. Something that I found useful was also to give the path to the specification repo that I have locally. It's super useful for certain kind of feature implementation.
Contributor
Author
There was a problem hiding this comment. Interesting. I think we would have to standardize on the location to put that here, but it could be a good candidate for each of our user-specific agents file.
Contributor
There was a problem hiding this comment. I agree, for sure we should not standardize the location, but it's a good add. |
||
| - `src/MongoDB.Bson/` - BSON for MongoDB | ||
| - `src/MongoDB.Driver/` - C# driver for MongoDB | ||
| - `src/MongoDB.Driver.Encryption/` - Client encryption (CSFLE with KMS). | ||
| - `src/MongoDB.Driver.Authentication.AWS/` - AWS IAM authentication | ||
| - `tests/MongoDB.Driver.Tests/` - Main C# driver tests | ||
| - `tests/MongoDB.Bson.Tests/` - BSON handling tests | ||
| - `tests/*/TestHelpers` - Common test utilities | ||
| - `tests/*` - Specialized tests; less common | ||
| - `tests/MongoDB.Driver.Tests/Specifications/` are JSON-driven tests using a common runner. | ||
|
|
||
| ## Editing | ||
| - Be careful to preserve file BOMs. | ||
|
|
||
| ## Commands | ||
| - Build: `dotnet build CSharpDriver.sln` | ||
| - Run all tests: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0` | ||
| - Run a single test class: `dotnet test tests/MongoDB.Driver.Tests/MongoDB.Driver.Tests.csproj -f net10.0 --filter "FullyQualifiedName~ClassName"` | ||
|
ajcvickers marked this conversation as resolved.
|
||
|
|
||
| ## Testing | ||
| - Tests cannot be run in parallel. | ||
| - A MongoDB connection is always available locally, so "integration" tests can be run as well as unit tests. Some test suites also require additional environment variables — if you need to run those tests and the variables are not set, stop and tell the user which variables are needed rather than working around it. | ||
|
|
||
| | Feature area | Required environment variables | | ||
| |---|---| | ||
| | Atlas Search | `ATLAS_SEARCH_TESTS_ENABLED`, `ATLAS_SEARCH_URI` | | ||
| | Atlas Search index helpers | `ATLAS_SEARCH_INDEX_HELPERS_TESTS_ENABLED`, `ATLAS_SEARCH_URI` | | ||
| | CSFLE / auto-encryption | `CRYPT_SHARED_LIB_PATH` | | ||
|
ajcvickers marked this conversation as resolved.
|
||
| | CSFLE with KMS mock servers | `KMS_MOCK_SERVERS_ENABLED` | | ||
| | CSFLE with AWS KMS | `CSFLE_AWS_TEMPORARY_CREDS_ENABLED` | | ||
| | CSFLE with Azure KMS | `CSFLE_AZURE_KMS_TESTS_ENABLED` | | ||
| | CSFLE with GCP KMS | `CSFLE_GCP_KMS_TESTS_ENABLED` | | ||
| | AWS authentication | `AWS_TESTS_ENABLED` | | ||
| | GSSAPI / Kerberos | `GSSAPI_TESTS_ENABLED`, `AUTH_HOST`, `AUTH_GSSAPI` | | ||
| | OIDC authentication | `OIDC_ENV` | | ||
| | X.509 authentication | `MONGO_X509_CLIENT_CERTIFICATE_PATH`, `MONGO_X509_CLIENT_CERTIFICATE_PASSWORD` | | ||
| | PLAIN authentication | `PLAIN_AUTH_TESTS_ENABLED` | | ||
| | SOCKS5 proxy | `SOCKS5_PROXY_SERVERS_ENABLED` | | ||
|
|
||
|
Contributor
There was a problem hiding this comment. Another line I have: "Do not strip BOMs: Source files may have a UTF-8 BOM ( (not sure if it's still an issue)
Contributor
Author
There was a problem hiding this comment. What issues have we had with BOMs?
Contributor
There was a problem hiding this comment. On some files both Claude and OpenCode were removing BOMs, so I was getting a change on the first line of some files. |
||
| ## Commit and PR Conventions | ||
|
|
||
| - The first commit message and the PR message start with a JIRA number: `CSHARP-1234: Description` | ||
| - The branch name will usually match the JIRA number: `CSHARP-1234` | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| @AGENTS.md |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This part about FluentAssertions.. I think we need to discuss about it in the team. Sometime ago we had a discussion about using the basic assertions against the fluent ones.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I have added FluentAssertions to my list of things to bring up in retrospective. For now, I think we should leave it--Claude explicitly called out that it was useful.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hm... just to leave the record: I do remember discussion about FluentAssertion turned to be commercial, and we should either stop using it, or pin the version and never bump it until it possible. But I do not remember if we really made any decisions. We also discussed possibility to switch to Shouldly.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Exactly what you said. I also think that at the time we didn't decide which direction to take though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this is the only more "contentious point". Should we leave it out and let the AI check the follow the conventions that are already in the file? Or check similar tests/tests for similar classes.