|
| 1 | +# CLA Troubleshooting Guide |
| 2 | + |
| 3 | +This guide provides step-by-step procedures for investigating and resolving issues with the Contributor License Agreement (CLA) bot used by .NET Foundation projects. |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +The .NET Foundation uses an automated CLA bot to verify that contributors have signed the required Contributor License Agreement before their pull requests can be merged. This bot is managed by Microsoft and integrated with GitHub. |
| 8 | + |
| 9 | +## Common Issues |
| 10 | + |
| 11 | +### Inconsistent CLA Bot Reports |
| 12 | + |
| 13 | +Sometimes the CLA bot may report different statuses for the same contributor across multiple pull requests. This can happen for several reasons: |
| 14 | + |
| 15 | +1. **Timing Issues**: The contributor signed the CLA between opening different PRs |
| 16 | +2. **Email Mismatch**: The contributor used different email addresses for different commits |
| 17 | +3. **Bot Synchronization**: The CLA bot database is out of sync with the actual signatures |
| 18 | +4. **Account Association**: The contributor's GitHub account is not properly associated with their CLA signature |
| 19 | + |
| 20 | +## Investigation Steps |
| 21 | + |
| 22 | +When you encounter inconsistent CLA bot reports, follow these steps to investigate: |
| 23 | + |
| 24 | +### Step 1: Verify Contributor Identity |
| 25 | + |
| 26 | +1. **Check the commit author information** in both PRs: |
| 27 | + ```bash |
| 28 | + # View commit details for a specific PR |
| 29 | + git log --format="%H %ae %an" origin/pull/PULL_NUMBER/head |
| 30 | + ``` |
| 31 | + |
| 32 | +2. **Compare email addresses** used in commits across the different PRs: |
| 33 | + - Are they using the same email address? |
| 34 | + - Is the email address associated with their GitHub account? |
| 35 | + - Do they have multiple email addresses configured? |
| 36 | + |
| 37 | +3. **Check GitHub profile**: |
| 38 | + - Visit the contributor's GitHub profile |
| 39 | + - Look at their configured email addresses (if public) |
| 40 | + - Check if they have verified their email addresses |
| 41 | + |
| 42 | +### Step 2: Check CLA Bot Comments |
| 43 | + |
| 44 | +1. **Review bot comments** on both pull requests: |
| 45 | + - Look for the exact message from the CLA bot |
| 46 | + - Note any differences in the messages |
| 47 | + - Check if the bot mentions specific issues (e.g., "email not found") |
| 48 | + |
| 49 | +2. **Look for CLA signature links**: |
| 50 | + - The bot typically provides a link to sign the CLA |
| 51 | + - Check if this link was followed by the contributor |
| 52 | + |
| 53 | +### Step 3: Verify CLA Signature Status |
| 54 | + |
| 55 | +Since the CLA bot is managed internally by Microsoft, project maintainers do not have direct access to the CLA database. To verify a contributor's CLA status: |
| 56 | + |
| 57 | +1. **Contact .NET Foundation Support**: |
| 58 | + - [Submit a Project Support Request](https://github.com/dotnet-foundation/projects/issues/new?assignees=ChrisSfanos&labels=project+support%2Ctriage&template=project-support-request.yml&title=%5BProject+Support%5D%3A+CLA+Status+Investigation) |
| 59 | + - Include: |
| 60 | + - Project name |
| 61 | + - Contributor's GitHub username |
| 62 | + - Links to all affected pull requests |
| 63 | + - Details about the inconsistency |
| 64 | + |
| 65 | +2. **Email Contact**: |
| 66 | + - For confidential matters, email: contact@dotnetfoundation.org |
| 67 | + - Include the same information as above |
| 68 | + |
| 69 | +3. **Discord Channel**: |
| 70 | + - Join the [.NET Foundation Discord](https://discord.gg/dotnet-foundation) |
| 71 | + - Post in the `#projects-support` channel |
| 72 | + - Provide the GitHub issue link for tracking |
| 73 | + |
| 74 | +### Step 4: Common Solutions |
| 75 | + |
| 76 | +While waiting for support team investigation, you can try these potential solutions: |
| 77 | + |
| 78 | +1. **Ask the contributor to re-trigger the CLA bot**: |
| 79 | + ``` |
| 80 | + @contributor Can you please comment `/cla` on this PR to re-trigger the CLA bot check? |
| 81 | + ``` |
| 82 | + Or ask them to add a trivial commit (e.g., whitespace change) to force a re-check. |
| 83 | + |
| 84 | +2. **Verify email configuration**: |
| 85 | + - Ask the contributor to ensure their commit email matches their CLA signature email |
| 86 | + - They can check their git config: `git config user.email` |
| 87 | + - They may need to amend commits if the email is wrong |
| 88 | + |
| 89 | +3. **Check for GitHub account linking**: |
| 90 | + - The contributor should ensure their GitHub account is properly linked to the email they used for the CLA |
| 91 | + - They can verify this in GitHub Settings > Emails |
| 92 | + |
| 93 | +4. **Re-sign the CLA** (if necessary): |
| 94 | + - If all else fails, the contributor may need to sign the CLA again |
| 95 | + - The CLA bot comment usually includes a link to the CLA signing page |
| 96 | + |
| 97 | +## Escalation Process |
| 98 | + |
| 99 | +If the issue cannot be resolved through the steps above: |
| 100 | + |
| 101 | +1. **Project Support Team** (@ChrisSfanos and team): |
| 102 | + - Has access to internal Microsoft resources |
| 103 | + - Can directly investigate CLA database issues |
| 104 | + - Can coordinate with the CLA bot team if needed |
| 105 | + |
| 106 | +2. **Timeline**: |
| 107 | + - Support requests are typically reviewed within a few business days |
| 108 | + - Complex CLA issues may require coordination with Microsoft Legal |
| 109 | + - Keep the contributor informed of progress |
| 110 | + |
| 111 | +3. **Interim Workarounds**: |
| 112 | + - While investigating, maintain communication with the contributor |
| 113 | + - Keep the PR open and mark it as "waiting for CLA verification" |
| 114 | + - Document the issue in the PR comments for transparency |
| 115 | + |
| 116 | +## Best Practices for Maintainers |
| 117 | + |
| 118 | +1. **Be Patient and Professional**: CLA issues can be frustrating, but they're usually resolvable. |
| 119 | + |
| 120 | +2. **Document Everything**: Keep clear records of what you've checked and attempted. |
| 121 | + |
| 122 | +3. **Communicate Clearly**: Keep contributors informed about what's happening and what's needed from them. |
| 123 | + |
| 124 | +4. **Don't Merge Without CLA**: Even if you trust the contributor, always wait for proper CLA verification before merging. |
| 125 | + |
| 126 | +5. **Report Patterns**: If you notice recurring issues with the CLA bot, report them to the support team so they can be addressed systematically. |
| 127 | + |
| 128 | +## Technical Details |
| 129 | + |
| 130 | +### How the CLA Bot Works |
| 131 | + |
| 132 | +1. **Trigger**: The bot is triggered automatically when: |
| 133 | + - A new PR is opened |
| 134 | + - New commits are pushed to an existing PR |
| 135 | + - Someone comments `/cla` on the PR |
| 136 | + |
| 137 | +2. **Verification**: The bot checks: |
| 138 | + - The email addresses of all commit authors in the PR |
| 139 | + - Whether those emails have associated CLA signatures in the database |
| 140 | + - Whether the signatures are current and valid |
| 141 | + |
| 142 | +3. **Status Update**: The bot posts a comment indicating: |
| 143 | + - ✅ All contributors have signed the CLA |
| 144 | + - ❌ One or more contributors need to sign the CLA |
| 145 | + - Links to sign the CLA if needed |
| 146 | + |
| 147 | +### Known Limitations |
| 148 | + |
| 149 | +1. **Email Matching**: The system relies on exact email matches. Case sensitivity and whitespace can cause issues. |
| 150 | + |
| 151 | +2. **GitHub Integration**: The bot depends on GitHub's commit author information, which can be configured incorrectly. |
| 152 | + |
| 153 | +3. **Caching**: There may be delays in status updates due to caching in various systems. |
| 154 | + |
| 155 | +4. **Multiple Accounts**: Contributors with multiple GitHub accounts or email addresses may encounter issues. |
| 156 | + |
| 157 | +## Additional Resources |
| 158 | + |
| 159 | +- [.NET Foundation CLA Information](https://github.com/dotnet-foundation/projects/blob/main/new-projects.md#signing-the-cla) |
| 160 | +- [Project Support Request Template](https://github.com/dotnet-foundation/projects/issues/new?assignees=ChrisSfanos&labels=project+support%2Ctriage&template=project-support-request.yml) |
| 161 | +- [.NET Foundation Discord](https://discord.gg/dotnet-foundation) |
| 162 | +- Email: contact@dotnetfoundation.org |
| 163 | + |
| 164 | +## Questions or Feedback |
| 165 | + |
| 166 | +If you have suggestions for improving this guide or encounter issues not covered here, please [open an issue](https://github.com/dotnet-foundation/projects/issues) in this repository. |
0 commit comments