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 request.

   • 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] <[[e-mail]]>

   • Example:

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

Example of a co-author failure showing SIGNED AGREEMENT MISSING

Example of a co-author failure showing UNKNOWN COMMIT AUTHOR

EasyCLA Integration with Co-Authors

• If co-author checks are enabled, EasyCLA validates each co-author against a signed CLA using the identifier that can be resolved from the co-author trailer.

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

• If a co-author is resolved but is not authorized under a signed CLA, EasyCLA can show SIGNED AGREEMENT MISSING.

• If a co-author cannot be resolved to a GitHub user, EasyCLA can show UNKNOWN COMMIT AUTHOR.

• Depending on the pull request, both badges can appear in the same EasyCLA comment.

Use one of the supported Co-authored-by: formats below. A non-public email can only be matched if that email was previously used for another CLA as a main commit author. Otherwise EasyCLA may not be able to find the co-author.

Supported Co-authored-by: formats include:

1. Anything <[e-mail]> - it will locate your GitHub user by id part.

2. Anything <[e-mail]> - it will locate your GitHub user by login part.

3. Anything <public-email> - it will locate your GitHub user by public-email part. Note that this email must be made public on GitHub.

4. Anything <other-email> - it will locate your GitHub user by other-email part but only if that email was used before for any other CLA as a main commit author.

5. login <any-valid-email> - it will locate your GitHub user by login part. Note that login part must be 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.

EasyCLA currently instructs contributors as follows: Alternatively, if the co-author should not be included, remove the Co-authored-by: line from the commit message.

After updating your commit message(s) by doing git commit --amend and then git push [--force], request re-running the CLA check by commenting on the pull request:

/easycla

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.

For automation users that should bypass CLA checks altogether, see Allowlisting Bots to Skip CLA.

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