EasyCLA and Co-Author Compliance Guide

This guide outlines the steps to ensure contributions using the "co-author" feature comply with EasyCLA.

Ensuring Contributor Compliance

1. Verify CLA Signature:

   • Every contributor, individual or organizational representative, must have a signed EasyCLA.

   • Use EasyCLA's dashboard or attempt a contribution to check the signature status. EasyCLA will provide instructions if a signature is missing.

2. Co-authors check:

   • Co-author checks are disabled by default. They can be enabled at the GitHub organization level.

   • Co-author checks can be enabled or disabled for:

     • A specific repository,

     • Repositories matching a pattern (regular expression),

     • All repositories in a GitHub organization.

   • Priority/order matters: Exact repository match takes precedence, followed by pattern match, and finally the organization-wide setting (wildcard).

   • For example, you can enable co-author checks for the entire organization, but disable them for a specific repository, or enable them only for repositories matching a certain pattern.

   • Enabling or disabling co-author checks can be configured by submitting a support ticket.

   • If co-author checks are enabled, EasyCLA will verify that all co-authors have signed the CLA.

3. Adding Co-Authors Correctly:

   • When using the "co-author" trailer in commit messages, include the following syntax for each co-author:

     Co-authored-by: [Full Name] <[[email protected]]>

   • Example:

     Implement new feature for API
     
     -Refactored data models
     -Created unit tests for edge cases
     
     Co-authored-by: Alice Johnson <[email protected]>
     Co-Authored-by: Bob Williams <[email protected]>
     Co-Authored-By: Lukasz Gryglicki <[email protected]>
     co-authored-by: Justyna Gryglicka <[email protected]>
     co-Authored-By: lukaszgryglicki2 <[email protected]>

EasyCLA Integration with Co-Authors

• EasyCLA verifies co-author email addresses against signed CLAs when a commit includes co-authors.

• Ensure all co-authors are registered and have a signed CLA.

• EasyCLA will block the pull request until compliance is met if any co-author is missing a signature.

Co-authors should not use "private" emails because EasyCLA verifies contributions via the email in the commit message. If the email is private, EasyCLA will fail to validate the commit.

How EasyCLA finds co-authors

• If the co-author line is Co-authored-by: Some Name <[email protected]>, EasyCLA will use the numeric id as the GitHub user ID to find the co-author using GitHub APIs.

• If it is Co-authored-by: Some Name <[email protected]>, EasyCLA will use login as the GitHub username.

• If it is Co-authored-by: Some Name <email@domain>, EasyCLA will try to find the co-author by email address.

• Note: the email must be public on the intended GitHub profile; otherwise, EasyCLA may not be able to find a match. EasyCLA will also try to identify the GitHub user by checking if the email has already been used to sign any CLA as a main author.

• If no user is found via email, EasyCLA will try to match the co-author’s name (from Co-authored-by: Name <email@domain>) as a GitHub username (this applies to some bots), provided the name is at least 3 characters long.

• If any co-author cannot be found, EasyCLA will add a comment on the pull request explaining how to correctly specify commit co-authors.

Tips for Successful Integration

1. Consistency: Ensure email addresses in co-author tags match those used for signing the CLA.

2. Training: Educate contributors on signing the CLA and including accurate information in co-author trailers.

Additional Resources

• GitHub Documentation

• You can set the email address used to author commits on GitHub.com and your computer. For more information see, Setting your commits email addresses