DOC: add copilot-instructions.md for coding-agent guidance by dlevy-msft-sql · Pull Request #406 · microsoft/mssql-python

dlevy-msft-sql · 2026-01-19T22:34:41Z

Work Item / Issue Reference

GitHub Issue: #247

Summary

adds .github/copilot-instructions.md: a from-scratch, repo-wide guide for coding agents working on mssql-python. it covers the architecture (python -> pybind ddbc_bindings -> odbc, with py-core/tds for bulk copy), the validated build/test/validation-gate commands, the C++ shutdown/init/arch hazards, the credential-scanning localhost rule, PR conventions, and a trust-and-validate close. it references the existing .github/prompts/ files instead of duplicating them, and every path plus the CI-enforced title prefixes were checked against the current tree.

github-actions · 2026-01-19T22:40:00Z

📊 Code Coverage Report

🔥 Diff Coverage 100%	🎯 Overall Coverage 80%	📈 Total Lines Covered: `6743` out of `8343` 📁 Project: `mssql-python`

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

No lines with coverage information in this diff.

📋 Files Needing Attention

📉 Files with overall lowest coverage (click to expand)

mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.pybind.ddbc_bindings.h: 59.9%
mssql_python.pybind.logger_bridge.hpp: 70.8%
mssql_python.pybind.connection.connection.cpp: 76.2%
mssql_python.pybind.ddbc_bindings.cpp: 76.2%
mssql_python.__init__.py: 77.3%
mssql_python.row.py: 77.6%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.connection.py: 83.6%
mssql_python.logging.py: 85.5%

🔗 Quick Links

⚙️ Build Summary	📋 Coverage Details
View Azure DevOps Build	Browse Full Coverage Report

Copilot

Pull request overview

This PR adds comprehensive LLM guidance documentation to help AI coding assistants work effectively with the mssql-python driver. It includes two new documentation files: llms.txt for end-user code suggestions and .github/copilot-instructions.md for repository contributors.

Changes:

Added llms.txt (269 lines) with usage examples, connection patterns, query syntax, error handling, and migration guidance
Added .github/copilot-instructions.md (257 lines) with build instructions, architecture overview, CI/CD details, and contributing guidelines

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
llms.txt	Provides comprehensive usage documentation for LLMs suggesting mssql-python code to end users, including connection strings, CRUD operations, and error handling
.github/copilot-instructions.md	Guides AI coding agents contributing to the repository with build system details, testing procedures, and architecture information

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

bewithgaurav

@dlevy-msft-sql - this is a great addition, I used copilot to review this PR on some more context that I have been working with, below are the details I'd like to add in this PR for both the files

Review Feedback - Elevating the LLM Guidance

Here are suggestions to make these instructions even more effective:

1. Reference Existing Prompts (copilot-instructions.md)

The repo already has excellent .prompt.md files in .github/prompts/. Instead of duplicating build/test instructions, reference them:

Development Workflows

This repository includes detailed prompt files for common tasks. Use these with `#`:

Task	Prompt	When to Use
First-time setup	`#setup-dev-env`	New machine, fresh clone
Build C++ extension	`#build-ddbc`	After modifying `.cpp`/`.h` files
Run tests	`#run-tests`	Validating changes
Create PR	`#create-pr`	Ready to submit changes

Workflow order for new contributors:

#setup-dev-env → Set up venv and dependencies
#build-ddbc → Build native extension
Make your changes
#run-tests → Validate
#create-pr → Submit

2. Add Anti-Patterns Section (copilot-instructions.md)

Telling AI what NOT to do is as important as what to do:

Critical Anti-Patterns (DO NOT)

NEVER hardcode connection strings - always use DB_CONNECTION_STRING env var
NEVER use pyodbc imports - this driver doesn't require external ODBC
NEVER modify files in mssql_python/libs/ - these are pre-built binaries
NEVER skip conn.commit() after INSERT/UPDATE/DELETE operations

3. Add Exception Hierarchy (copilot-instructions.md)

Critical for error handling guidance:

Error (base)
├── DatabaseError
│   ├── InterfaceError      # Driver/interface issues
│   ├── OperationalError    # Connection/timeout issues  
│   ├── IntegrityError      # Constraint violations
│   ├── ProgrammingError    # SQL syntax errors
│   └── DataError           # Invalid data processing
└── Warning

4. Add AI Agent Behavioral Instructions (copilot-instructions.md)

When Modifying Code

Python Changes

Preserve existing error handling patterns from exceptions.py
Use context managers (with) for all connection/cursor operations
Update __all__ exports if adding public API
Add corresponding test in tests/test_*.py

C++ Changes

Follow RAII patterns for resource management
Use py::gil_scoped_release for blocking ODBC operations
Update mssql_python.pyi type stubs if changing Python API

5. Add Debugging Quick Reference (copilot-instructions.md)

Symptom	Likely Cause	Solution
`ImportError: ddbc_bindings`	Extension not built	Run `#build-ddbc`
`Connection timeout`	Missing env var	Set `DB_CONNECTION_STRING`
`dylib not found` (macOS)	Library paths	Run `configure_dylibs.sh`

6. Resolve Black Version Comment

The existing review comment about Black version pinning is unresolved - either remove the version pin or add explicit rationale.

Overall:
The distinction between llms.txt (user-facing API docs) and copilot-instructions.md (contributor-facing) is well thought out! The existing .prompt.md files are nice and well-used - consider cross-referencing them to avoid duplication. 👍

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dlevy-msft-sql

Reviewed against the repo style guide and existing patterns. A few issues — mostly around audience separation (dev vs. user), stale references, and some code sample issues. Details in inline comments.

Add two documentation files to help AI coding assistants work effectively with the mssql-python driver: llms.txt (user-facing, 256 lines): - Installation, Quick Start, connection string patterns - CRUD operations, parameterized queries, transactions - Stored procedures with OUTPUT param workaround - Error handling with full exception hierarchy - Connection pooling, pyodbc comparison and migration - Platform support matrix (SUSE x64-only noted) .github/copilot-instructions.md (contributor-facing, 263 lines): - Cross-references to .github/prompts/ workflow files - Build system instructions (Windows/macOS/Linux) - Project architecture with complete file tree - CI/CD pipeline details (5 GitHub workflows, ADO pipelines) - Anti-patterns, debugging quick reference - PR requirements and contributing guidelines

rewrites .github/copilot-instructions.md from scratch against the current repo: the python -> pybind ddbc_bindings -> odbc call stack (py-core/TDS for bulkcopy), the validated build/test/validation-gate commands, the C++ shutdown and static-handle and error-code hazards, the credential-scanning localhost rule, PR conventions, and a trust-and-validate close. every path and the CI-enforced title prefixes were checked against the tree. drops llms.txt: it's a website-root convention, isn't shipped in the wheel (not in package_data) and nothing discovers it from a repo root, so it's inert here. the contributor instructions file is the surface that's actually consumed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings January 19, 2026 22:34

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 22:35 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Comment thread .github/copilot-instructions.md Outdated

Comment thread llms.txt Outdated

dlevy-msft-sql requested a review from Copilot January 19, 2026 22:47

Copilot started reviewing on behalf of dlevy-msft-sql January 19, 2026 22:47 View session

Copilot AI reviewed Jan 19, 2026

View reviewed changes

Comment thread .github/copilot-instructions.md Outdated

dlevy-msft-sql added the pr-size: small Minimal code update label Jan 22, 2026

bewithgaurav requested changes Jan 29, 2026

View reviewed changes

This was referenced Jan 29, 2026

DOC: Add comprehensive BUILDGUIDE.md with cross-platform build instructions and VS Code setup #156

Closed

DOC: Add comprehensive .github/copilot-instructions.md for coding agent onboarding #247

Closed

dlevy-msft-sql requested a review from Copilot January 30, 2026 00:12

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 00:12 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

Comment thread llms.txt Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread llms.txt Outdated

Comment thread llms.txt Outdated

Comment thread llms.txt Outdated

Comment thread .github/copilot-instructions.md Outdated

dlevy-msft-sql requested a review from Copilot January 30, 2026 01:14

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 01:14 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

Comment thread .github/copilot-instructions.md Outdated

dlevy-msft-sql requested a review from Copilot January 30, 2026 01:29

Copilot started reviewing on behalf of dlevy-msft-sql January 30, 2026 01:50 View session

Copilot AI reviewed Jan 30, 2026

View reviewed changes

dlevy-msft-sql requested a review from bewithgaurav February 2, 2026 02:29

bewithgaurav previously approved these changes Feb 6, 2026

View reviewed changes

dlevy-msft-sql commented Feb 8, 2026

View reviewed changes

Comment thread llms.txt Outdated

Comment thread llms.txt Outdated

Comment thread llms.txt Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread .github/copilot-instructions.md Outdated

Comment thread .github/copilot-instructions.md Outdated

dlevy-msft-sql dismissed bewithgaurav’s stale review via 3773e92 February 8, 2026 04:57

dlevy-msft-sql force-pushed the docs/llm-usage-guide branch from 3393f5d to ab117b6 Compare February 8, 2026 05:17

dlevy-msft-sql force-pushed the docs/llm-usage-guide branch from ab117b6 to 89f2787 Compare February 8, 2026 05:25

dlevy-msft-sql and others added 2 commits March 6, 2026 17:23

Merge branch 'microsoft:main' into docs/llm-usage-guide

0b4900a

bewithgaurav changed the title ~~DOC: Add llms.txt and copilot-instructions.md for LLM guidance~~ DOC: add copilot-instructions.md for coding-agent guidance Jul 15, 2026

Merge branch 'main' into docs/llm-usage-guide

aba28dc

bewithgaurav approved these changes Jul 16, 2026

View reviewed changes

sumitmsft approved these changes Jul 16, 2026

View reviewed changes

gargsaumya approved these changes Jul 16, 2026

View reviewed changes

bewithgaurav merged commit 0966b05 into microsoft:main Jul 16, 2026
24 checks passed

Uh oh!

Conversation

dlevy-msft-sql commented Jan 19, 2026 • edited by bewithgaurav Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Work Item / Issue Reference

Summary

Uh oh!

github-actions Bot commented Jan 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Code Coverage Report

🔥 Diff Coverage

100%

🎯 Overall Coverage

80%

Diff Coverage

Diff: main...HEAD, staged and unstaged changes

📋 Files Needing Attention

🔗 Quick Links

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

bewithgaurav left a comment

Choose a reason for hiding this comment

Review Feedback - Elevating the LLM Guidance

1. Reference Existing Prompts (copilot-instructions.md)

Development Workflows

2. Add Anti-Patterns Section (copilot-instructions.md)

Critical Anti-Patterns (DO NOT)

3. Add Exception Hierarchy (copilot-instructions.md)

4. Add AI Agent Behavioral Instructions (copilot-instructions.md)

When Modifying Code

Python Changes

C++ Changes

5. Add Debugging Quick Reference (copilot-instructions.md)

6. Resolve Black Version Comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

dlevy-msft-sql left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

dlevy-msft-sql commented Jan 19, 2026 •

edited by bewithgaurav

Loading

github-actions Bot commented Jan 19, 2026 •

edited

Loading