Difference between revisions of "CLA/Implementation Requirements"

From Eclipsepedia

< CLA
Jump to: navigation, search
(Contact Store)
(Gerrit)
Line 54: Line 54:
 
Once code has been reviewed and approved by an Eclipse project committer, they may push it into the master git repository for the project.
 
Once code has been reviewed and approved by an Eclipse project committer, they may push it into the master git repository for the project.
  
The [https://github.com/waynebeaton/gerrit-cla-plugin Eclipse Gerrit plugin] is hosted on GitHub.
+
The [https://github.com/waynebeaton/gerrit-cla-plugin Eclipse Gerrit plugin] is hosted on GitHub. For more information, please see {{Bug|401239}}.
  
 
===Contact Store===
 
===Contact Store===

Revision as of 16:25, 2 May 2013

Contents

Roles

Committer: A person who is covered by an Eclipse Foundation Committer Agreement and who has write access to the Eclipse Foundation source code repositories.

Contributor: A person who wishes to contribute code or documentation to one or more Eclipse projects. A Contributor must be covered by a CLA.

User: A person who has an Eclipse Foundation user id (e.g. an "Eclipse account").

Requirements

Data Requirements

The following data elements will have to be stored for retrieval:

The actual CLA documents will have to be either stored as they are completed (in HTML or PDF), or we will have to be able to recreate them on demand. For example, if the IP team needed to print a copy of a user's CLA five years after it was submitted, we need to be able to do that.

All of the data on the CLA document will have to be stored for retrieval and archival. Currently this includes:

  • Contributor legal name
  • Contributor public name
  • Email address
  • Physical mailing address
  • Country
  • (TBC) Electronic signature (“I ACCEPT”)
  • Active date (e.g. date the CLA was submitted)
  • (TBC) Expiry date (e.g. Active date plus three years)

RESTful Service Requirements

It must be possible to programmatically confirm that a given email address has an active CLA on file. This service will return true if the email address corresponds to an active CLA, or to an active Committer Agreement.

So the call would be simply passing an email address, and the return values could include:

  • true or false (if false, the following values are null)
  • role: (committer or contributor)
  • date: the date of the agreement.

Results will be provided in JSON (default) or XML Format.

Access control to this service is TBC.

Gerrit

The following requirements illustrate use cases for pushing code into Gerrit for review by an Eclipse project.

  • A project committer can push a commit on behalf of themselves or any other project committer
  • A project committer can push a commit on behalf of a contributor if:
    • The contributor has a valid CLA at the time of the push; and
    • The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author
  • A contributor can push a commit if:
    • They have a valid CLA at the time of the push;
    • The commit's author credentials match the user identity;
    • The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author

Note that we assume that a single "push" operation may include multiple commits.

Once code has been reviewed and approved by an Eclipse project committer, they may push it into the master git repository for the project.

The Eclipse Gerrit plugin is hosted on GitHub. For more information, please see bug 401239.

Contact Store

As part of the CLA registration process, Gerrit calls out to a Contact Store. The contact store is provided with the values entered by the user on the CLA creation form in a PGP-encrypted file attachment. The workflow looks like this:

CLA-ContactStore.png

The contact store:

  • Creates a user record in the Foundation database for the Gerrit user if necessary;
  • Stores decrypted CLA "document" in the Foundation database (we just store the content entered by the user on the form, not the actual document);
  • Updates LDAP to include the user in the CLA group ("Eclipse-CLA-v1"); and
  • Returns OK/200 indicating success or 500 indicating failure.

Upon success, the user will be considered good-to-go.

For more information, please see bug 406099.

Open questions:

  • Can we turn off the PGP encryption of CLA data (so that we don't need to decrypt it)?
    We don't particularly need the PGP encryption as the communication between Gerrit and the contact store uses HTTPS and run entirely inside the eclipse.org domain.

Git

All Git pushes will be directed through Gerrit.

Implementation

We will implement CLA support using Gerrit. Background discussion in on bug 401239.

  1. Investigate what out-of-the-box Gerrit can provide
    • Store CLA data in Foundation database
  2. Consider implementing plugin with CommitValidationListener to provide finer-grained control

Workflow Examples

Warning2.png
These workflows need to be reviewed. Our understanding of the problem has evolved since these were authored.


Completing a CLA

A high-level description of the workflow for CLAs is as follows. This description assumes that the person involved has never been involved with Eclipse before. To assist in the narrative, we will refer to the contributor as “Joe”.

  1. Joe becomes interested in an Eclipse project (let’s use EGit as an example) and gets access to the source code (this may be via a social coding website such as Github, but not necessarily).
  2. Screenshot 1: User Registration
    Joe hacks some code and comes up with a feature enhancement or bug fix that he would like to contribute to to EGit. The first thing Joe has to do is register at eclipse.org as a User. This is done via the existing registration page, with one addition: asking the user if they want to provide a CLA after registration. See Screenshot 1.
  3. Once Joe has created his eclipse.org user id, he will be prompted to also complete the CLA.
    • When the CLA comes up, it will be filled with the data already provided when he created the userid (e.g. his email address, and public name). See Screenshot 2.
      Screenshot 2: Signing a CLA
  4. When completing the CLA, Joe has to tick the boxes beside the three questions in the CLA, as well as providing all of the information at the bottom of the form.
    • Once Joe presses “Accept”, he immediately has an active CLA in place and proceed with contributing his code.

Contributing Code Via Bugzilla

Contributor (Joe) contributes code to a project via Bugzilla attachment.

  1. Joe attaches his code to a bug as a Git commit record, with Joe as the Author of the commit
    • i.e. Joe’s name and email address are in the author fields in the commit record).
  2. The project Committer on the project who wishes to apply the patch to the EGit project uses look-up service (i.e. web page) to verify that Joe has an active CLA (using Joe's email address)
  3. When the Committer attempts to push the commit to the Git repository at Eclipse, a check is initiated to confirm that the commit author (i.e. the contributor) has a valid CLA on file.
    • The push is rejected if an active CLA cannot be identified.

Note that project committers do not require CLAs. Any checks performed to identify a CLA will consider the committer status of the author.

Contributing Code Via Gerritt

  1. For Joe to contribute code via Gerritt, he will have to push his code to Gerritt as a git commit record, with Joe as the Author of the commit (i.e. Joe’s name and email address are in the commit record).
  2. Gerrit will verify that a CLA is on file for every commit in the push
    1. The push operation will be rejected if a CLA cannot be identified for each commit.

Project committers assume that the author of any commit that has made it into Gerrit is either a project committer, or has a valid CLA on file.

Other Use Cases

  • A Contributor changes his email address.
  • A Contributor changes his physical address.
  • A Contributor changes his country of residence.
  • A Contributor changes his employer and has to re-submit his CLA.
  • A Contributor becomes a Committer.
  • A Contributor requests that their CLA be terminated.

This page is moderated by the EMO.