FIX: Contribution process for internal/external contributors & documentation

.github/PULL_REQUEST_TEMPLATE.MD

@@ -1,9 +1,20 @@
-### ADO Work Item Reference  
-<!-- Insert your ADO Work Item ID below (e.g. AB#37452) -->
+### Work Item / Issue Reference  
+<!-- 
+IMPORTANT: Please follow the PR template guidelines below.
+For mssql-python maintainers: Insert your ADO Work Item ID below (e.g. AB#37452)
+For external contributors: Insert Github Issue number below (e.g. #149)
+Only one reference is required - either GitHub issue OR ADO Work Item.
+-->
+
+<!-- mssql-python maintainers: ADO Work Item -->
 > AB#<WORK_ITEM_ID>
+
+<!-- External contributors: GitHub Issue -->
+> GitHub Issue: #<ISSUE_NUMBER>
+
 -------------------------------------------------------------------
 ### Summary   
-<!-- Insert your Copilot Generated Summary below -->  
+<!-- Insert your summary of changes below. Minimum 10 characters required. -->  
 
 
 <!-- 
@@ -29,4 +40,16 @@ REFACTOR: (short-description)
 
 > For release related changes, without any feature changes
 RELEASE: #<RELEASE_VERSION> (short-description) 
+
+### Contribution Guidelines
+
+External contributors:
+- Create a GitHub issue first: https://github.com/microsoft/mssql-python/issues/new
+- Link the GitHub issue in the "GitHub Issue" section above
+- Follow the PR title format and provide a meaningful summary
+
+mssql-python maintainers:
+- Create an ADO Work Item following internal processes
+- Link the ADO Work Item in the "ADO Work Item" section above  
+- Follow the PR title format and provide a meaningful summary
 -->

.github/workflows/pr-format-check.yml

@@ -17,47 +17,59 @@ jobs:
           script: |
             const title = context.payload.pull_request.title;
             const body = context.payload.pull_request.body;
+            const prAuthor = context.payload.pull_request.user.login;
 
+            // Validate title prefix for all contributors
             const validTitlePrefixes = [
-              'FEAT:', 'CHORE:', 'FIX:', 'DOC:', 'STYLE:', 'REFACTOR:', 'RELEASE:'
+              'FEAT:', 'CHORE:', 'FIX:', 'DOC:', 'STYLE:', 'REFACTOR:', 
+              'RELEASE:'
             ];
 
-            const hasValidPrefix = validTitlePrefixes.some(prefix => title.startsWith(prefix));
+            const hasValidPrefix = validTitlePrefixes.some(prefix => 
+              title.startsWith(prefix));
 
             if (!hasValidPrefix) {
               core.setFailed(`❌ PR title must start with one of the allowed prefixes:\n${validTitlePrefixes.join(', ')}`);
             }
 
-            const azureWorkItemLinkPattern = /https:\/\/sqlclientdrivers\.visualstudio\.com\/[^\/]+\/_workitems\/edit\/\d+/i;
+            // Validate that either GitHub issue link or ADO Work Item link is present
+            const azureWorkItemLinkPattern = 
+              /https:\/\/sqlclientdrivers\.visualstudio\.com\/[^\/]+\/_workitems\/edit\/\d+/i;
+            const githubIssueLinkPattern = 
+              /(https:\/\/github\.com\/microsoft\/mssql-python\/issues\/\d+|#\d+)/i;
+
             const hasWorkItemLink = azureWorkItemLinkPattern.test(body);
+            const hasGitHubIssueLink = githubIssueLinkPattern.test(body);
 
-            if (!hasWorkItemLink) {
-              core.setFailed(`❌ PR should contain a valid ADO Work Item ID.\nExpected a hyperlink in the format: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/<ID>\nPlease ensure the ADO task hyperlink is present in the PR description.`);
+            if (!hasWorkItemLink && !hasGitHubIssueLink) {
+              core.setFailed(`❌ PR must contain either a valid GitHub issue link OR a valid ADO Work Item link.\nGitHub issue format: https://github.com/microsoft/mssql-python/issues/XXX or #XXX\nADO Work Item format: https://sqlclientdrivers.visualstudio.com/.../_workitems/edit/<ID>\nPlease include at least one reference in the PR description.\nFor more information, see CONTRIBUTING.md.`);
             }
-
-            // Check if PR description contains a meaningful summary section with actual content
-            const summaryPattern = /###\s*Summary\s*\r?\n([\s\S]*?)(\r?\n###|$)/;
+
+            // Check if PR description contains a meaningful summary section 
+            // with actual content (for all contributors)
+            const summaryPattern = 
+              /###\s*Summary\s*\r?\n([\s\S]*?)(\r?\n###|$)/;
             const summaryMatch = body.match(summaryPattern);
-            
+
             let hasValidSummary = false;
-            
+
             if (summaryMatch && summaryMatch[1]) {
               // Extract the summary content
               const summaryContent = summaryMatch[1];
-              
+
               // Remove all HTML comments including the template placeholder
-              const contentWithoutComments = summaryContent.replace(/<!--[\s\S]*?-->/g, '');
-
+              const contentWithoutComments = 
+                summaryContent.replace(/<!--[\s\S]*?-->/g, '');
+
               // Remove whitespace and check if there's actual text content
               const trimmedContent = contentWithoutComments.trim();
-              
+
               // Check if there's at least 10 characters of meaningful content
               hasValidSummary = trimmedContent.length >= 10;
             }
-            
+
             if (!hasValidSummary) {
-              core.setFailed(`❌ PR must contain a meaningful summary section with actual text content (minimum 10 characters). 
-              Please add a clear description under the '### Summary' heading in your PR description.`);
+              core.setFailed(`❌ PR must contain a meaningful summary section with actual text content (minimum 10 characters).\nPlease add a clear description under the '### Summary' heading in your PR description.`);
             }
       - name: Add size label based on PR diff
         uses: actions/github-script@v7

CONTRIBUTING.md

@@ -11,4 +11,32 @@ instructions provided by the bot. You will only need to do this once across all
 
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
 For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
-or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+## Before Contributing
+
+### For External Contributors
+
+If you are an external contributor (not a Microsoft organization member), please follow these steps:
+
+1. **Create a GitHub Issue First**: Before submitting a pull request, create a GitHub issue describing the bug, feature request, or improvement you want to contribute.
+2. **Link the Issue in Your PR**: When you submit your pull request, please use the PR template and include a link to the GitHub issue in the PR description using the format: `https://github.com/microsoft/mssql-python/issues/XXX`
+3. **Follow PR Guidelines**: Ensure your PR title follows the required prefix format (FEAT:, FIX:, DOC:, etc.) and includes a meaningful summary.
+
+### For Microsoft Organization Members
+
+If you are a Microsoft organization member (internal contributor):
+
+1. **Create an ADO Work Item**: Follow your internal process to create an Azure DevOps (ADO) work item.
+2. **Link the ADO Work Item**: Include the ADO work item link in your PR description using the format: `https://sqlclientdrivers.visualstudio.com/.../workitems/edit/ID`
+3. **Follow PR Guidelines**: Ensure your PR title follows the required prefix format and includes a meaningful summary.
+
+## Pull Request Requirements
+
+All pull requests must include:
+
+- **Valid Title Prefix**: Your PR title must start with one of: `FEAT:`, `CHORE:`, `FIX:`, `DOC:`, `STYLE:`, `REFACTOR:`, or `RELEASE:`
+- **Meaningful Summary**: Include a clear description of your changes under the "### Summary" section in the PR description (minimum 10 characters)
+- **Issue/Work Item Link** (only one required): 
+  - External contributors: Link to a GitHub issue
+  - Microsoft org members: Link to an ADO work item