Repository navigation
Add agent instructions from encryption-info review lessons - #5116
Open
priyankatiwari08 wants to merge 1 commit into
Open
priyankatiwari08 wants to merge 1 commit into
priyankatiwari08 wants to merge 1 commit into
Conversation
Turn recurring review feedback from the connection-encryption-info PRs (#4830, #5043, #4831, #4835, #5051) into general rules for coding style, best practices, documentation, TDS constants, API contract wording, test authoring, and handling review feedback. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 72fef407-b7e6-4f74-b02b-72f9d8f4797e
priyankatiwari08
requested review from
a team
and
a balanced review from Copilot
November 19, 2026 08:30
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new policies exclude required API-boundary conversions, documented exception recovery, and public serialization constructors, while the instruction scope omits implementation and test files.
4 open issues
What changed in this PR
This documentation-only PR turns recurring feedback from the connection-encryption-info work into reusable guidance for SqlClient contributors and coding agents. It does not change driver behavior.
Changes:
- Expands coding policies for readability, type safety, exception handling, and state management.
- Adds guidance for test coverage, member documentation, API contracts, and protocol constants.
- Establishes a review-feedback workflow and links it from feature and bug-fix prompts.
| File | Description |
|---|---|
policy/coding-style.md |
Adds readability, member organization, nullability, visibility, and naming rules. |
policy/coding-best-practices.md |
Adds type-safety and state-management rules; extends exception guidance. |
AGENTS.md |
Summarizes new testing rules and adds the review-feedback workflow. |
.github/prompts/implement-feature.prompt.md |
Links feature work to the review-feedback workflow. |
.github/prompts/fix-bug.prompt.md |
Links bug fixes to the review-feedback workflow. |
.github/instructions/testing.instructions.md |
Adds property, assertion, enum, setting-matrix, and simulator guidance. |
.github/instructions/tds-protocol.instructions.md |
Directs protocol constants into TdsEnums.cs. |
.github/instructions/documentation.instructions.md |
Adds internal-member, parameter, limit, and platform-comment guidance. |
.github/instructions/api-design.instructions.md |
Clarifies contract wording and unknown-versus-absent values. |
Review effort: Balanced
Comment on lines
+143
to
+145
| ### Implementation and Internal Members | ||
| - Give every new member an XML doc block, including `internal` and `private` members. | ||
| - Use `<inheritdoc/>` on overrides and interface implementations instead of copying text. |
Comment on lines
+40
to
+44
| - Never use `catch (Exception)` or a bare `catch` that swallows the exception | ||
| or converts it into a default value. | ||
| - Catch only the specific exception types the called API documents, and only | ||
| where the code can recover. Before adding a `try`/`catch`, name what can | ||
| actually throw; if nothing can, do not add it. |
Comment on lines
+49
to
+52
| - Keep strong types end to end. On .NET, never cast a BCL type such as | ||
| `SslProtocols` or `TlsCipherSuite` to `int` or another primitive. When a | ||
| type is missing on .NET Framework, confine the primitive and its conversion | ||
| to that `#if NETFRAMEWORK` branch. |
Comment on lines
+90
to
+91
| 1. Use the narrowest visibility possible. Members of `internal` or `private` types are not | ||
| `public` unless they implement an interface or override a public virtual member. |
This branch has not been deployed
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.

Description
Several review rounds on latest PRs raised the same concerns repeatedly. Most come from agent habits that our instructions don't currently push back on. This PR turns those comments into general rules in the files agents load, so the same issues are less likely to come up on later PRs.
Rules added and the review comments behind them
policy/coding-style.md: simple, obvious codeifinstead of compound patterns, nested ternaries, or??/?.chains: too clever, simple and readable.new(): type-implied new().usingdeclarations: using declaration. Auto-properties: auto-properties.#nullable enablein new files: should be nullable?, why is this needed.policy/coding-best-practices.mdcatch (Exception), catch only documented types: what can throw?, never swallow fatal exceptions..github/instructions/documentation.instructions.md: docs on internal members,<inheritdoc/>, limits stated with units and rationale,<param>docs for changed values, and comments explaining framework-only blocks: inheritDoc, block comments, size and units, encrypt parameter, .NET Framework only..github/instructions/tds-protocol.instructions.md: protocol constants go inTdsEnums: magic number..github/instructions/api-design.instructions.md: contract wording must match the code, andnull(unknown) must stay distinct fromNone(known absent): doesn't imply causation, ambiguous sentence, soften, null vs None..github/instructions/testing.instructions.md(Required Test Authoring Rules 10-15, with a pointer inAGENTS.md): one test per property, positive assertions, enum coverage throughEnum.GetValues, an explicit setting/mode matrix, reuse ofTdsServer, and names that describe behavior: missing an Assert, test all values, not testing all modes, where is Strict?, remembering history, unclear what is tested, use existing TdsServer, apply test instructions.AGENTS.md: new "Addressing Review Feedback" section (linked from theimplement-featureandfix-bugprompts). It covers applying a principle across the whole PR and later stacked PRs, answering "why" inline, removing mechanisms that aren't needed, fixing shared root causes once, and self-reviewing withsqlclient-code-reviewbefore each review round. Motivated by make a pass over this PR, future PRs in the stack, here and throughout, and the #4831 review asking for better answers to "why" questions.Guidelines
Please review the contribution guidelines before submitting a pull request: