Add context files for AI assisted development

[Mahendra Chavan (machavan)]

Description:

Adds structured documentation to enable effective AI-assisted development with the MSSQL JDBC driver:

ARCHITECTURE.md - Driver architecture and component overview
GLOSSARY.md - Standardized terminology and concepts
PATTERNS.md - Design patterns and coding conventions

Why: These files provide context that AI coding assistants (like GitHub Copilot) can use to generate more accurate, consistent code that follows established project patterns.

How to use:

Reference files directly: "Kimin Ryu (@workspace) using patterns from PATTERNS.md, add a new connection option"
Ask architecture questions: "Kimin Ryu (@workspace) explain how bulk copy sends data over TDS"
Generate consistent code: "Kimin Ryu (@workspace) add error handling following the project patterns"

This is a step toward making the codebase more AI-friendly and improving developer productivity

[Copilot]

Pull request overview

This pull request adds comprehensive documentation for AI-assisted development with the MSSQL JDBC driver. The documentation consists of three well-structured markdown files providing architecture overview, terminology reference, and code patterns.

Changes:

• Added ARCHITECTURE.md with driver architecture, layer descriptions, package structure, and data flow diagrams
• Added GLOSSARY.md with standardized terminology, acronyms, and coding conventions used in the codebase
• Added PATTERNS.md with practical code examples for exception handling, logging, resource management, and other common tasks

Reviewed changes

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

File	Description
ARCHITECTURE.md	Comprehensive architectural documentation including layer diagrams, package structure, data flows, and design patterns to help AI assistants understand the overall structure
GLOSSARY.md	Reference documentation of terms, acronyms, data types, connection properties, and conventions used throughout the codebase for consistent terminology
PATTERNS.md	Practical code examples and patterns for common tasks like exception handling, logging, connection properties, TDS protocol operations, bulk copy, and Always Encrypted features

Based on my thorough review of the three documentation files, I have verified:

1. Code accuracy: The code patterns in PATTERNS.md match actual usage in the codebase (verified against SQLServerException.makeFromDriverError, Logger.getLogger, SQLServerDriverBooleanProperty, TDS tokens, etc.)

2. Terminology consistency: Terms are used consistently across all three files (e.g., TDS, MARS, Always Encrypted, bulk copy, etc.)

3. Technical accuracy:

   • File names match actual files (e.g., tdsparser.java, IOBuffer.java)
   • Class names and method signatures are correct
   • Enum values and constants are accurate
   • Package structure reflects the actual codebase

4. Documentation quality:

   • Clear structure with table of contents
   • Well-organized sections
   • Practical examples with context
   • Consistent formatting

5. Grammar and spelling: No issues found

The documentation is well-written, technically accurate, and will be valuable for AI-assisted development. The files provide the right level of detail to help AI coding assistants understand the codebase structure, terminology, and patterns without being overwhelming.

---

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

[Mahendra Chavan (machavan)]

/azp run

[azure-pipelines]

Azure Pipelines could not run because the pipeline triggers exclude this branch/path.

[Divang Sharma (divang)]

We might be also including below points:

PATTERNS.md
Add "Anti-Patterns" section - What NOT to do:

Anti-Patterns (Avoid These)

Don't concatenate SQL

// BAD - SQL injection risk
String sql = "SELECT * FROM " + userInput;

// GOOD - Use parameterized queries
String sql = "SELECT * FROM users WHERE id = ?";

GLOSSARY.md
Add "Common Error Messages" section - Would help AI diagnose issues:

Common Error Messages

Error Key	Meaning
R_connectionClosed	Connection was closed before operation
R_invalidQueryTimeout	Negative or invalid timeout value
R_tableNameNull	Table name parameter was null

ARCHITECTURE.md
Add an "Entry Points" section - This helps AI understand where to start:

Entry Points

Use Case	Entry Point Class
DriverManager connection	SQLServerDriver.connect()
DataSource connection	SQLServerDataSource.getConnection()
Bulk copy operations	SQLServerBulkCopy.writeToServer()
Always Encrypted setup	SQLServerConnection.registerColumnEncryptionKeyStoreProviders()

[Copilot]

Pull request overview

Copilot reviewed 3 out of 4 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.