DOC: Add llms.txt and copilot-instructions.md for LLM guidance #406
Conversation
- Add llms.txt with comprehensive usage examples for LLMs to suggest to users - Add .github/copilot-instructions.md for AI coding agents contributing to repo - Includes connection patterns, query examples, error handling, Azure Entra ID - Covers build system, project architecture, CI/CD, and contributing guidelines
📊 Code Coverage Report
Diff CoverageDiff: main...HEAD, staged and unstaged changesNo lines with coverage information in this diff. 📋 Files Needing Attention📉 Files with overall lowest coverage (click to expand)mssql_python.pybind.logger_bridge.hpp: 58.8%
mssql_python.pybind.logger_bridge.cpp: 59.2%
mssql_python.row.py: 66.2%
mssql_python.pybind.ddbc_bindings.cpp: 69.4%
mssql_python.pybind.ddbc_bindings.h: 69.7%
mssql_python.pybind.connection.connection.cpp: 73.6%
mssql_python.ddbc_bindings.py: 79.6%
mssql_python.pybind.connection.connection_pool.cpp: 79.6%
mssql_python.connection.py: 84.1%
mssql_python.cursor.py: 84.7%🔗 Quick Links
|
There was a problem hiding this comment.
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.
- Fix architecture detection reference: ddbc_bindings.py not __init__.py - Fix stored procedure syntax: use positional params without named param mixing
There was a problem hiding this comment.
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.
.github/copilot-instructions.md
Outdated
| # Python formatting (use black 26.1.0 to match CI) | ||
| pip install black==26.1.0 |
There was a problem hiding this comment.
The comment suggests using Black version 26.1.0 to "match CI", but the GitHub Actions workflow (lint-check.yml) and Azure DevOps pipelines don't pin a specific Black version - they just install the latest version with pip install black. This could be misleading for developers. Consider either removing the version pin or updating the CI to actually use a specific version for consistency.
| # Python formatting (use black 26.1.0 to match CI) | |
| pip install black==26.1.0 | |
| # Python formatting (black) | |
| pip install black |
CI uses unpinned black, not 26.1.0. Also add --line-length=100 to match CI command.
bewithgaurav
left a comment
bewithgaurav
left a comment
There was a problem hiding this comment.
@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_STRINGenv var - NEVER use
pyodbcimports - 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_releasefor blocking ODBC operations - Update
mssql_python.pyitype 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. 👍
2 participants
Summary
This PR adds comprehensive documentation to help LLMs work effectively with the mssql-python driver, both for suggesting usage examples to end users and for contributing to the repository.
Changes
New Files:
llms.txt(243 lines) - Usage guide for LLMs suggesting code to users?and%(name)sstyles).github/copilot-instructions.md(283 lines) - Instructions for AI coding agents contributing to the repoRelated Issues
Supersedes #247 - This PR includes a corrected and expanded version of the
copilot-instructions.mdfile with:logging.pyinstead oflogging_config.py)__init__.pyinstead ofddbc_bindings.py)26.1.0)pyproject.tomlreferenceTesting
No code changes - documentation only. Verified: