Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "ECA/Implementation Requirements"

< ECA
(Contact Store)
m (Frederic.gurr.eclipse.org moved page CLA/Implementation Requirements to ECA/Implementation Requirements)
(13 intermediate revisions by 6 users not shown)
Line 3: Line 3:
 
'''Committer''': A person who is covered by an Eclipse Foundation Committer Agreement and who has write access to the Eclipse Foundation source code repositories.
 
'''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.
+
'''Contributor''': A person who wishes to contribute code or documentation to one or more Eclipse projects. A Contributor must be covered by an ECA.
  
 
'''User''': A person who has an Eclipse Foundation user id (e.g. an "Eclipse account").
 
'''User''': A person who has an Eclipse Foundation user id (e.g. an "Eclipse account").
  
 
=Requirements=
 
=Requirements=
 +
==Workflow==
 +
 +
[[Image:CLA-ContactStore.png|center]]
 +
 +
* User creates an ECA via web form;
 +
* User pushes to Gerrit or Git
 +
 +
Any registered user can push to Gerrit; only committers can push to Git. More discussion below.
 +
 
==Data Requirements==
 
==Data Requirements==
  
The following data elements will have to be stored for retrieval:
+
The text of the ECA is found here: [http://www.eclipse.org/legal/ECA.html http://www.eclipse.org/legal/ECA.html].
 +
 
 +
The following data elements are collected:
 +
 
 +
* Agreement to the four assertions posed on the form;
 +
* Email address;
 +
* Legal name;
 +
* Public name (optional; if different from legal name);
 +
* Physical (postal) mailing address; and
 +
* Electronic signature (“I AGREE”).
 +
 
 +
The date/time that the ECA is captured is recorded when it is stored in the database. Every new ECA is valid for three years.
 +
 
 +
The Foundation database, as the holder of the ECA documents, is the central authority with regard to who has a ECA and who does not.
  
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.
+
Every user that has a valid ECA is also a member of an LDAP group ("eclipsecla"); this LDAP group is used for most ECA-status queries.
  
All of the data on the CLA document will have to be stored for retrieval and archival. Currently this includes:
+
The actual ECA "document" is stored in JSON format. The JSON payload contains the value provided for each captured value along with a snapshot of the ECA document text.
*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==
 
==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.
+
It must be possible to programmatically confirm that a given email address has an active ECA on file. This service will return true if the email address corresponds to an active ECA, or to an active Committer Agreement.
  
 
So the call would be simply passing an email address, and the return values could include:
 
So the call would be simply passing an email address, and the return values could include:
Line 36: Line 50:
  
 
Access control to this service is TBC.
 
Access control to this service is TBC.
 +
 +
==Registration==
 +
 +
ECAs are registered through a web form. When submitted, the web form:
 +
 +
* Creates a record for the contributor in the Foundation database if necessary;
 +
* Creates a document record for the contributor that records the ECA data; and
 +
* Updates LDAP to indicate that the user has a valid ECA on file.
 +
 +
''We need to open a bug to track this.''
  
 
==Gerrit==
 
==Gerrit==
Line 43: Line 67:
 
* 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 themselves or any other project committer
 
* A project committer can push a commit on behalf of a contributor if:
 
* 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 contributor has a valid ECA at the time of the push; and
 
** The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author
 
** The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author
 
* A contributor can push a commit if:
 
* A contributor can push a commit if:
** They have a valid CLA at the time of the push;
+
** They have a valid ECA at the time of the push;
 
** The commit's author credentials match the user identity;
 
** 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
 
** 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.
+
Note that a single "push" operation may include multiple commits; each commit must comply with these requirements.
  
 
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.
Line 56: Line 80:
 
The [https://github.com/waynebeaton/gerrit-cla-plugin Eclipse Gerrit plugin] is hosted on GitHub. For more information, please see {{Bug|401239}}.
 
The [https://github.com/waynebeaton/gerrit-cla-plugin Eclipse Gerrit plugin] is hosted on GitHub. For more information, please see {{Bug|401239}}.
  
===Capturing CLAs with Gerrit===
+
More about the "Signed-off-by" statement here:
 +
[https://git.eclipse.org/r/Documentation/user-signedoffby.html Gerrit Documentation - Signed-off-by Lines]
  
We explored using Gerrit to capture CLAs, but decided that Gerrit is insufficient for our requirements. Specifically:
+
===Sample output===
 +
 
 +
Here is the output from the Gerrit plugin in response to an attempt to push two commits. The first commit is valid (the author has a ECA, and has signed-off on the commit). The second commit is invalid (not signed-off by the author). The push operation is atomic, so both commits are rejected.
 +
 
 +
<pre>[wayne@baxter Junk]$ git push origin HEAD:refs/for/master
 +
Username for 'http://localhost.localdomain:8080': wbeaton
 +
Password for 'http://wbeaton@localhost.localdomain:8080':
 +
Counting objects: 5, done.
 +
Delta compression using up to 4 threads.
 +
Compressing objects: 100% (4/4), done.
 +
Writing objects: 100% (4/4), 433 bytes, done.
 +
Total 4 (delta 2), reused 0 (delta 0)
 +
remote: Resolving deltas: 100% (2/2)
 +
remote: Processing changes: refs: 1, done   
 +
remote: ----------
 +
remote: Reviewing commit: commit 26469b6af47a8e6e6870d219ab9632ca576b0e4c 1371517714 ----sp
 +
remote: Authored by: marvin <wayne.beaton@eclipse.org>
 +
remote:
 +
remote: The author is not a committer on the project.
 +
remote: The author has a current Eclipse Contributor Agreement (ECA) on file.
 +
remote: The author has "signed-off" on the contribution.
 +
remote:
 +
remote: This commit passes Eclipse validation.
 +
remote: ----------
 +
remote: Reviewing commit: commit 599b523019fa17625c264d4fb753c9bbb46955e4 1371517730 ----sp
 +
remote: Authored by: marvin <wayne.beaton@eclipse.org>
 +
remote:
 +
remote: The author is not a committer on the project.
 +
remote: The author has a current Eclipse Contributor Agreement (ECA) on file.
 +
remote: error: The author has not "signed-off" on the contribution.
 +
remote: Please see http://wiki.eclipse.org/ECA
 +
To http://localhost.localdomain:8080/Junk
 +
! [remote rejected] HEAD -> refs/for/master (The contributor must "sign-off" on the contribution.)
 +
error: failed to push some refs to 'http://localhost.localdomain:8080/Junk'</pre>
 +
 
 +
===Capturing ECAs with Gerrit===
 +
 
 +
We explored using Gerrit to capture ECAs, but decided that Gerrit is insufficient for our requirements. Specifically:
  
 
* Gerrit hard-codes the fields that it accepts and we cannot (easily) add/change those fields;
 
* Gerrit hard-codes the fields that it accepts and we cannot (easily) add/change those fields;
* Gerrit provides no means for pre-populating the CLA form with information we already know (like the email address); and
+
* Gerrit provides no means for pre-populating the ECA form with information we already know (like the email address); and
 
* Gerrit PGP-encrypts data that it sends to a "contact store" (decrypting isn't hard, but it increases the complexity of creating and maintaining the contact store script).
 
* Gerrit PGP-encrypts data that it sends to a "contact store" (decrypting isn't hard, but it increases the complexity of creating and maintaining the contact store script).
  
Line 68: Line 130:
 
==Git==
 
==Git==
  
All Git pushes will be directed through Gerrit.
+
The following requirements illustrate use cases for pushing code into Git.
 +
 
 +
* 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 ECA 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 cannot push unless they themselves are a committer
  
 
=Implementation=
 
=Implementation=
  
We will implement CLA support using Gerrit. Background discussion in on {{Bug|401239}}.
+
We will implement ECA support using Gerrit. Background discussion in on {{Bug|401239}}.
  
 
# Investigate what out-of-the-box Gerrit can provide
 
# Investigate what out-of-the-box Gerrit can provide
#* Store CLA data in Foundation database
+
#* Store ECA data in Foundation database
 
# Consider implementing plugin with CommitValidationListener to provide finer-grained control
 
# Consider implementing plugin with CommitValidationListener to provide finer-grained control
  
Line 82: Line 150:
 
{{Warning|These workflows need to be reviewed. Our understanding of the problem has evolved since these were authored.}}
 
{{Warning|These workflows need to be reviewed. Our understanding of the problem has evolved since these were authored.}}
  
==Completing a CLA==
+
==Completing a ECA==
  
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”.
+
A high-level description of the workflow for ECAs 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”.
  
 
#Joe becomes interested in an Eclipse project (let’s use [http://www.eclipse.org/egit 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).
 
#Joe becomes interested in an Eclipse project (let’s use [http://www.eclipse.org/egit 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).
#[[Image:CLA-Register.png|thumb|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.
+
#[[Image:CLA-Sign.png|thumb|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 ECA after registration. See Screenshot 1.
#Once Joe has created his eclipse.org user id, he will be prompted to also complete the CLA.
+
#Once Joe has created his eclipse.org user id, he will be prompted to also complete the ECA.
#*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. [[Image:CLA-Sign.png|thumb|Screenshot 2: Signing a CLA]]
+
#*When the ECA 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. [[Image:CLA-Register.png|thumb|Screenshot 2: Signing a ECA]]
#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.
+
#When completing the ECA, Joe has to tick the boxes beside the three questions in the ECA, 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.
+
#*Once Joe presses “Accept”, he immediately has an active ECA in place and proceed with contributing his code.
  
 
==Contributing Code Via Bugzilla==
 
==Contributing Code Via Bugzilla==
Line 99: Line 167:
 
#Joe attaches his code to a bug as a Git commit record, with Joe as the Author of the commit
 
#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).
 
#* i.e. Joe’s name and email address are in the author fields in the commit record).
#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)
+
#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 ECA (using Joe's email address)
#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.
+
#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 ECA on file.
#* The push is rejected if an active CLA cannot be identified.
+
#* The push is rejected if an active ECA 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.''
+
''Note that project committers do not require ECAs. Any checks performed to identify a ECA will consider the committer status of the author.''
  
 
==Contributing Code Via Gerritt==
 
==Contributing Code Via Gerritt==
  
 
# 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).
 
# 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).
# Gerrit will verify that a CLA is on file for every commit in the push
+
# Gerrit will verify that a ECA is on file for every commit in the push
*# The push operation will be rejected if a CLA cannot be identified for each commit.
+
*# The push operation will be rejected if a ECA 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.
+
Project committers assume that the author of any commit that has made it into Gerrit is either a project committer, or has a valid ECA on file.
  
 
==Other Use Cases==
 
==Other Use Cases==
Line 118: Line 186:
 
* A Contributor changes his physical address.
 
* A Contributor changes his physical address.
 
* A Contributor changes his country of residence.
 
* A Contributor changes his country of residence.
* A Contributor changes his employer and has to re-submit his CLA.  
+
* A Contributor changes his employer and has to re-submit his ECA.  
 
* A Contributor becomes a Committer.
 
* A Contributor becomes a Committer.
* A Contributor requests that their CLA be terminated.
+
* A Contributor requests that their ECA be terminated.
  
 
''This page is moderated by the EMO.''
 
''This page is moderated by the EMO.''
  
[[Category:CLA]]
+
[[Category:ECA]]

Revision as of 06:27, 19 April 2017

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 an ECA.

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

Requirements

Workflow

CLA-ContactStore.png
  • User creates an ECA via web form;
  • User pushes to Gerrit or Git

Any registered user can push to Gerrit; only committers can push to Git. More discussion below.

Data Requirements

The text of the ECA is found here: http://www.eclipse.org/legal/ECA.html.

The following data elements are collected:

  • Agreement to the four assertions posed on the form;
  • Email address;
  • Legal name;
  • Public name (optional; if different from legal name);
  • Physical (postal) mailing address; and
  • Electronic signature (“I AGREE”).

The date/time that the ECA is captured is recorded when it is stored in the database. Every new ECA is valid for three years.

The Foundation database, as the holder of the ECA documents, is the central authority with regard to who has a ECA and who does not.

Every user that has a valid ECA is also a member of an LDAP group ("eclipsecla"); this LDAP group is used for most ECA-status queries.

The actual ECA "document" is stored in JSON format. The JSON payload contains the value provided for each captured value along with a snapshot of the ECA document text.

RESTful Service Requirements

It must be possible to programmatically confirm that a given email address has an active ECA on file. This service will return true if the email address corresponds to an active ECA, 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.

Registration

ECAs are registered through a web form. When submitted, the web form:

  • Creates a record for the contributor in the Foundation database if necessary;
  • Creates a document record for the contributor that records the ECA data; and
  • Updates LDAP to indicate that the user has a valid ECA on file.

We need to open a bug to track this.

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 ECA 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 ECA 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 a single "push" operation may include multiple commits; each commit must comply with these requirements.

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.

More about the "Signed-off-by" statement here: Gerrit Documentation - Signed-off-by Lines

Sample output

Here is the output from the Gerrit plugin in response to an attempt to push two commits. The first commit is valid (the author has a ECA, and has signed-off on the commit). The second commit is invalid (not signed-off by the author). The push operation is atomic, so both commits are rejected.

[wayne@baxter Junk]$ git push origin HEAD:refs/for/master
Username for 'http://localhost.localdomain:8080': wbeaton 
Password for 'http://wbeaton@localhost.localdomain:8080': 
Counting objects: 5, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 433 bytes, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2)
remote: Processing changes: refs: 1, done    
remote: ----------
remote: Reviewing commit: commit 26469b6af47a8e6e6870d219ab9632ca576b0e4c 1371517714 ----sp
remote: Authored by: marvin <wayne.beaton@eclipse.org>
remote: 
remote: The author is not a committer on the project.
remote: The author has a current Eclipse Contributor Agreement (ECA) on file.
remote: The author has "signed-off" on the contribution.
remote: 
remote: This commit passes Eclipse validation.
remote: ----------
remote: Reviewing commit: commit 599b523019fa17625c264d4fb753c9bbb46955e4 1371517730 ----sp
remote: Authored by: marvin <wayne.beaton@eclipse.org>
remote: 
remote: The author is not a committer on the project.
remote: The author has a current Eclipse Contributor Agreement (ECA) on file.
remote: error: The author has not "signed-off" on the contribution.
remote: Please see http://wiki.eclipse.org/ECA
To http://localhost.localdomain:8080/Junk
 ! [remote rejected] HEAD -> refs/for/master (The contributor must "sign-off" on the contribution.)
error: failed to push some refs to 'http://localhost.localdomain:8080/Junk'

Capturing ECAs with Gerrit

We explored using Gerrit to capture ECAs, but decided that Gerrit is insufficient for our requirements. Specifically:

  • Gerrit hard-codes the fields that it accepts and we cannot (easily) add/change those fields;
  • Gerrit provides no means for pre-populating the ECA form with information we already know (like the email address); and
  • Gerrit PGP-encrypts data that it sends to a "contact store" (decrypting isn't hard, but it increases the complexity of creating and maintaining the contact store script).

For more information, please see bug 406099.

Git

The following requirements illustrate use cases for pushing code into Git.

  • 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 ECA 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 cannot push unless they themselves are a committer

Implementation

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

  1. Investigate what out-of-the-box Gerrit can provide
    • Store ECA 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 ECA

A high-level description of the workflow for ECAs 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 ECA after registration. See Screenshot 1.
  3. Once Joe has created his eclipse.org user id, he will be prompted to also complete the ECA.
    • When the ECA 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 ECA
  4. When completing the ECA, Joe has to tick the boxes beside the three questions in the ECA, as well as providing all of the information at the bottom of the form.
    • Once Joe presses “Accept”, he immediately has an active ECA 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 ECA (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 ECA on file.
    • The push is rejected if an active ECA cannot be identified.

Note that project committers do not require ECAs. Any checks performed to identify a ECA 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 ECA is on file for every commit in the push
    1. The push operation will be rejected if a ECA 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 ECA 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 ECA.
  • A Contributor becomes a Committer.
  • A Contributor requests that their ECA be terminated.

This page is moderated by the EMO.

Back to the top