|
| 1 | +#GitHub Copilot Instructions for dotnet/SqlClient |
| 2 | + |
| 3 | +##🧑💻 Roles and Responsibilities |
| 4 | +-**Triage**: Review new issues, categorize them, and assign them to appropriate team members. |
| 5 | +-**Fixing Issues**: Address bugs, implement feature requests, and complete tasks as assigned. |
| 6 | +-**Writing Tests**: Ensure all changes are covered by unit tests and integration tests. |
| 7 | +-**Documentation**: Update documentation for public APIs, features, and usage examples. |
| 8 | +-**Pull Requests**: Create and submit PRs for review, ensuring they follow project conventions and include necessary tests and documentation. |
| 9 | +-**Code Reviews**: Review PRs from other contributors, providing feedback and suggestions for improvements. |
| 10 | +-**Continuous Improvement**: Identify areas for improvement in the code base, documentation, and processes, and implement changes to enhance the project. |
| 11 | + |
| 12 | +##📚 Project Overview |
| 13 | +This project is a .NET data provider for SQL Server, enabling .NET applications to interact with SQL Server databases. It supports various features like connection pooling, transaction management, and asynchronous operations. |
| 14 | +The project is structured to support both .NET Framework and .NET Core, with platform-specific implementations in`netfx/` and`netcore/` directories. |
| 15 | +The project includes: |
| 16 | +-**Public APIs**: Defined in`ref/` directories for both .NET Framework and .NET Core. |
| 17 | +-**Implementations**: Actual code in`src/` directories for both platforms. |
| 18 | +-**Tests**: Located in the`tests/` directory, covering unit and integration tests. |
| 19 | +-**Unit Tests**: Located in`tests/UnitTests/` directory, which includes tests for individual components and methods. |
| 20 | +-**Functional Tests**: Located in`tests/FunctionalTests/` directory, which includes tests for various features and functionalities that can be run without a SQL Server instance. |
| 21 | +-**Manual Tests**: Located in`tests/ManualTests/` directory, which includes tests that require a SQL Server instance to run. |
| 22 | +-**Documentation**: Found in the`doc/` directory, including API documentation, usage examples. |
| 23 | +-**Policies**: Contribution guidelines, coding standards, and review policies in the`policy/` directory. |
| 24 | +-**Building**: The project uses MSBuild for building and testing, with configurations and targets defined in the`build.proj` file, whereas instructions are provided in the`BUILDGUIDE.md` file. |
| 25 | +-**CI/CD**: ADO Pipelines for CI/CD and Pull request validation are defined in the`eng/` directory, ensuring code quality and automated testing. |
| 26 | + |
| 27 | +##📦 Products |
| 28 | +This project includes several key products and libraries that facilitate SQL Server connectivity and data access: |
| 29 | +-**Microsoft.Data.SqlClient**: The primary library for SQL Server data access, providing a rich set of APIs for connecting to SQL Server databases, executing commands, and retrieving data. |
| 30 | +-**Microsoft.Data.SqlClient.AlwaysEncrypted.AzureKeyVaultProvider**: Enables Always Encrypted with Azure Key Vault integration, allowing SQL Server column encryption and decryption using keys managed in Azure Key Vault. |
| 31 | +-**Microsoft.SqlServer.Server**: Supplies APIs for SQL Server-specific features, including user-defined types (UDTs) and SQL Server-specific attributes. |
| 32 | + |
| 33 | +##🛠️ Key Features |
| 34 | +-**Connectivity to SQL Server**: Provides robust and secure connections to SQL Server databases, using various authentication methods, such as Windows Authentication, SQL Server Authentication, and Azure Active Directory authentication, e.g.`ActiveDirectoryIntegrated`,`ActiveDirectoryPassword`,`ActiveDirectoryServicePrincipal`,`ActiveDirectoryInteractive`,`ActiveDirectoryDefault`, and`ActiveDirectoryManagedIdentity`. |
| 35 | +-**Connection Resiliency**: Implements connection resiliency features to handle transient faults and network issues, ensuring reliable database connectivity. |
| 36 | +-**TLS Encryption**: Supports secure connections using TLS protocols to encrypt data in transit. Supports TLS 1.2 and higher, ensuring secure communication with SQL Server. Supported encryption modes are: |
| 37 | +-**Optional**: Encryption is used if available, but not required. |
| 38 | +-**Mandatory**: Encryption is mandatory for the connection. |
| 39 | +-**Strict**: Enforces strict TLS requirements, ensuring only secure connections are established. |
| 40 | +-**TLS 1.3 Support**: Supports TLS 1.3 for enhanced security and performance in data transmission when connecting with 'Strict' encryption mode. |
| 41 | +-**TDS Protocol**: Implements the Tabular Data Stream (TDS) protocol for communication with SQL Server, supported protocol versions include TDS 7.4 and 8.0. |
| 42 | +-**Data Access**: Supports executing SQL commands, retrieving data using`SqlDataReader`, and managing data with`SqlCommand` and`SqlConnection` objects. |
| 43 | +-**MultipleActiveResultSets (MARS)**: Supports Multiple Active Result Sets, allowing multiple active commands to be executed on a single connection. |
| 44 | +-**Asynchronous Operations**: Supports async/await patterns for non-blocking database operations. |
| 45 | +-**Connection Pooling**: Efficiently manages database connections in pools to improve performance. |
| 46 | +-**Transaction Management**: Supports transaction management using local transaction management and Global transactions using MSDTC for data integrity and consistency. |
| 47 | +-**Parameterization**: Supports prevention of SQL injection attacks by using parameterized queries. |
| 48 | +-**Data Types**: Supports a wide range of SQL Server data types, including Json, Vector, custom types and UDTs. |
| 49 | +-**Data Encryption**: Supports data encryption for secure data transmission. |
| 50 | +-**Logging and Diagnostics**: Provides event source tracing diagnostic capabilities for troubleshooting. |
| 51 | +-**Failover Support**: Handles automatic failover scenarios for high availability. |
| 52 | +-**Cross-Platform Support**: Compatible with both .NET Framework and .NET Core, allowing applications to run on Windows, Linux, and macOS. |
| 53 | +-**Column Encryption AKV Provider**: Supports Azure Key Vault (AKV) provider for acquiring keys from Azure Key Vault to be used for encryption and decryption. |
| 54 | + |
| 55 | +##🧩 SNI Implementations |
| 56 | +There are two implementations of the SQL Server Network Interface (SNI) layer used in this project: |
| 57 | +-**Managed SNI**: A managed implementation of SNI that is used in .NET Core and .NET 5+ environments. It provides cross-platform support for SQL Server connectivity. |
| 58 | +-**Native SNI**: A native implementation of SNI that is used in .NET Framework and .NET Core environments on Windows. It's shipped as part of the`Microsoft.Data.SqlClient.SNI` and`Microsoft.Data.SqlClient.SNI.Runtime` packages. |
| 59 | +-**Microsoft.Data.SqlClient.SNI**: This package provides the native SNI layer for .NET Framework applications. |
| 60 | +-**Microsoft.Data.SqlClient.SNI.Runtime**: This package provides the native SNI layer for .NET Core applications on Windows. |
| 61 | + |
| 62 | +##📌 Instructions for Copilot |
| 63 | + |
| 64 | +###🐛 Triage Issues |
| 65 | +When a new issue is created, follow these steps: |
| 66 | +1.**Acknowledge Receipt**: Respond within 48 hours to confirm the issue is being triaged. |
| 67 | +2.**Set Issue Type**: |
| 68 | +- Update issue type as`Bug`,`Feature`,`Task`, or`Epic` if not done already, based on: |
| 69 | +- Use`Bug` for issues opened following`ISSUE_TEMPLATE\bug-report.md` template, and is complaining about an unexpected behavior. |
| 70 | +- Use`Feature` for issues opened following`ISSUE_TEMPLATE\feature_request.md` template, containing proposals to incorporate. |
| 71 | +- Use`Task` for issues opened as sub-issues. |
| 72 | +- Use`Epic` for issues acting as a high-level work linked to multiple sub-issues. |
| 73 | +3.**Request Missing Information**: If any required details are missing based on the issue template, ask the reporter to provide them. |
| 74 | +4.**Labeling**: Apply appropriate labels like`Area\Engineering`,`Area\Json`,`Area\AKV Provider`,`Area\Connection Pooling`, etc. based on the issue content. |
| 75 | +- Use`Triage Needed :new:` for new issues that need initial review. |
| 76 | +- Use`Performance :chart_with_upwards_trend:` for issues that are targeted to performance improvements/concerns. |
| 77 | +- Use`Needs more info :information_source:` for issues that require additional information. |
| 78 | +5.**Link Related Issues**: If the issue is related to other issues, link them for better context. |
| 79 | +6.**Add Comments**: As you triage issues, comment on the issue to: |
| 80 | +- Confirm receipt and triage status. |
| 81 | +- Ask for any missing information. |
| 82 | +- Provide initial thoughts or questions to clarify the issue. |
| 83 | +- Include links to relevant documentation or code examples. |
| 84 | +- Use the`@` mention feature to notify relevant team members or stakeholders. |
| 85 | + |
| 86 | +###🛠️ Fixing Issues |
| 87 | +- Focus on issues assigned to you. |
| 88 | +- For issues labeled`Needs more info :information_source:`, ask for clarifications or additional details. |
| 89 | +- For issues labeled`Performance :chart_with_upwards_trend:`, prioritize performance-related improvements. |
| 90 | +- Use the issue description to understand the problem and identify the root cause. |
| 91 | +- If the issue is a bug, ensure you can reproduce it with the provided code sample. |
| 92 | +- If the issue is a feature request, review the proposal and assess its feasibility. |
| 93 | +- If the issue is a task, follow the instructions provided in the issue description. |
| 94 | +- If the issue is an epic, break it down into smaller tasks or bugs and create sub-issues as needed. |
| 95 | +- Cross-reference issue descriptions with code in`src/` folders, especially in`netfx/src/` and`netcore/src/`. |
| 96 | +- If public APIs are changed, update corresponding`ref/` projects. |
| 97 | +- Add or update tests in`tests/` to validate the fix. |
| 98 | + |
| 99 | +###🧪 Writing Tests |
| 100 | +- For every bug fix, ensure there are unit tests and manual (integration) tests that cover the scenario. |
| 101 | +- For new features, write tests that validate the functionality. |
| 102 | +- Use the existing test framework in the`tests/` directory. |
| 103 | +- Follow the naming conventions and structure of existing tests. |
| 104 | +- Ensure tests are comprehensive and cover edge cases. |
| 105 | +- If the issue involves changes to public APIs, update the corresponding`ref/` projects to reflect those changes. |
| 106 | +- Add sample code snippets in the 'doc/samples/' directory to demonstrate the new or fixed functionality and link them in the documentation in`doc/` folder. |
| 107 | + |
| 108 | +###📝 Documentation |
| 109 | +- All public documentation for APIs should be updated in the`doc/` directories. |
| 110 | +- When adding or changing XML docs, ensure they are clear and follow the existing style. |
| 111 | + |
| 112 | +###🔁 Creating Pull Requests |
| 113 | +- Use the`Fixes #issue_number` syntax in the PR description to automatically close the issue when the PR is merged. |
| 114 | +- Include a summary of the fix and link to the related issue |
| 115 | +- Add`[x]` checkboxes for: |
| 116 | +-[ ] Tests added or updated |
| 117 | +-[ ] Public API changes documented |
| 118 | +-[ ] Verified against customer repro (if applicable) |
| 119 | +-[ ] Ensure no breaking changes introduced |
| 120 | +- Ensure the PR passes all CI checks before merging. |
| 121 | + |
| 122 | +###✅ Closing Issues |
| 123 | +- Add a comment summarizing the fix and referencing the PR |
| 124 | + |
| 125 | +###⚙️ Automating Workflows |
| 126 | +- Auto-label PRs based on folder paths (e.g., changes in`netcore/src` →`area-netcore`) and whether they add new public APIs or introduce a breaking change. |
| 127 | +- Suggest changelog entries for fixes in`CHANGELOG.md` |
| 128 | +- Tag reviewers based on`CODEOWNERS` file |
| 129 | + |
| 130 | +##🧠 Contextual Awareness |
| 131 | +- Always check for platform-specific differences between`netfx` and`netcore` |
| 132 | +- Respect API compatibility rules across .NET versions |
| 133 | +- Do not introduce breaking changes without proper justification and documentation |
| 134 | +- Use the`doc/` directory for any new documentation or updates to existing documentation |
| 135 | +- Use the`tests/` directory for any new tests or updates to existing tests |
| 136 | +- Use the`doc/samples/` directory for any new code samples or updates to existing samples |
| 137 | +- Use the`policy/` directory for any new policies or updates to existing policies |
| 138 | + |
| 139 | +##Constraints |
| 140 | +- Do not modify the`CODEOWNERS` file directly. |
| 141 | +- Do not modify the`CHANGELOG.md` file directly. |
| 142 | +- Do not close issues without a fix or without providing a clear reason. |
| 143 | + |
| 144 | +##📝 Notes |
| 145 | +- Update policies and guidelines in the`policy/` directory as needed based on trending practices and team feedback. |
| 146 | +- Regularly review and update the`doc/` directory to ensure it reflects the current state of the project. |