|
| 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. |
0 commit comments