Difference between revisions of "Development Resources/Handling Git Contributions"

From Eclipsepedia

Jump to: navigation, search
(Scenario)
(Bugzilla)
(34 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Git makes it easy to pull contributions from other repositories and make them part of your own. It feels wrong to do the same thing we do with CVS: attach a patch that is later added to the repository by a committer. The natural thing to do in Git is to pull the contribution in question from the contributor's Git repository.  Regardless of the mechanism used to actually get the code into an Eclipse project's Git repository, the Eclipse IP Policy and Due Diligence Process must be followed.
+
This page is directed at Eclipse Committers. If you are not an Eclipse committer but want to contribute to an Eclipse project via Git or Gerrit, please see [[Development Resources/Contributing via Git|Contribution via Git]].
 +
 
 +
__TOC__
 +
 
 +
Git makes it easy to pull contributions from other repositories and make them part of your own. The natural thing to do in Git is to pull the contribution in question from the contributor's Git repository.  Regardless of the mechanism used to actually get the code into an Eclipse project's Git repository, the Eclipse IP Policy and Due Diligence Process must be followed.
  
 
One of the main issues that we need to address is that we need to form a connection between code that has been contributed and a statement of provenance, rights, and licensing. You know, lawyer stuff.
 
One of the main issues that we need to address is that we need to form a connection between code that has been contributed and a statement of provenance, rights, and licensing. You know, lawyer stuff.
  
Git does a great job of keeping track of author information, but there is no built in way to keep track of all the other stuff. At some point in the hopefully-not-too-distant-future, we'll be able to use Gerrit for this (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=283749 Bug 283749]). In the meantime, we have to bridge the old world with the new.
+
For more information, please see [http://www.eclipse.org/legal/committerguidelines.php#Due_Diligence Due Diligence Procedures] in the Committer Due Diligence Guidelines.
  
=Scenario=
+
=Overview=
  
An individual has forked one of the eclipse.org projects and has issued a pull request for a commit record that they would like to contribute to the eclipse.org project.
+
Contributions received through Git or Gerrit are subject to the following:
  
# A contributor who is not currently a committer on the project indicates that they've authored some code that they'd like to contribute to the project (this may occur through any number of communication channels).
+
* A project committer can push a commit on behalf of themselves or any other project committer
#* The developer who authored the code is referred to as the "contributor" or "author"
+
* A project committer can push a commit on behalf of a contributor if:
# Eclipse project committer agrees the contribution is something they would like to include in their project.
+
** The contributor has a valid CLA at the time of the push; and
# Contributor (author) or project committer creates a bugzilla that include URL pointers to the refs (commit record) in the source repository.  
+
** The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author
#* e.g., https://github.com/waynebeaton/KittyMunch3/commit/d08bf60f7de9a5e6b48823a115d8054f2a871819
+
* A contributor can push a commit to Gerrit if:
# The contributor (author) provides a statement regarding the provenance, rights, and license of the code in a comment on the Bugzilla record.
+
** They have a valid CLA at the time of the push;
#* e.g., "I wrote all this code and have the rights to contribute it to Eclipse under the eclipse.org web site terms of use."
+
** The commit's author credentials match the user identity;
# If required by the IP Due Diligence Process (e.g. if the contribution exceeds 250 lines), the committer creates a CQ (including the URL of the ref) and waits for "check in" permission
+
** The commit message contains a "Signed-off-by:" statement with credentials matching those of the commit author
# Project committer merges the pull request back into the eclipse.org project git repository.
+
 
#* The "Committer" name and email in the Git commit record must be set to the committer's information. The "email" field must be the Eclipse committer ID, or the committer email address as recorded for the committer account at the Eclipse Foundation. See [[Git#Committing_and_pushing|Committing and Pushing]] for more information.
+
Note that we assume that a single "push" operation may include multiple commits.
#* The "Author" name and email in the Git commit record must be set to the contributor's information. See [http://stackoverflow.com/questions/750172/how-do-i-change-the-author-of-a-commit-in-git How do I change the author of a commit in git?] for help.
+
 
 +
Here's some handy boilerplate text that you can use to tell a contributor what they need to do:
 +
 
 +
<pre>Before your contribution can be accepted by the project, you need to create and
 +
electronically sign the Eclipse Foundation Contributor License Agreement (CLA) and sign
 +
off on the Eclipse Foundation Certificate of Origin.  
 +
 
 +
For more information, please visit
 +
 
 +
http://wiki.eclipse.org/Development_Resources/Contributing_via_Git</pre>
 +
 
 +
=Git=
 +
 
 +
An individual (the "Contributor") has forked one of the eclipse.org projects and has issued a pull request for a commit record that they would like to contribute to the eclipse.org project.  
 +
 
 +
# If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
 +
#* An Eclipse Foundation account can be created on any of forges managed by the Eclipse Foundation (e.g. [http://projects.eclipse.org projects.eclipse.org], [http://locationtech.org locationtech.org]);
 +
# Contributor creates a Git commit:
 +
#* Author email address must set to the address associated with the author's Eclipse Foundation account;
 +
#* The Contributor must signed-off-by the Contribution, indicating that they are in compliance with the Eclipse Foundation Contributor’s [http://www.eclipse.org/legal/CoO.php Certificate of Origin];
 +
#* The "Signed-off-by" credentials must match the author credentials;
 +
#* Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
 +
#* If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345);
 +
# Contributor connects with the project via a transparent communication channel (e.g. project mailing list, forum, or Bugzilla record) to indicate that they've authored some code that they'd like to contribute to the project:
 +
#* Contributor provides a link to the contribution's commit for a "Git pull";
 +
# Project committer initiates IP Due Diligence process:
 +
#* If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit; and
 +
#* Committer waits for check-in authorization
 +
# Project committer merges the commit record into one of the project's Git repositories:
 
#* In simple cases, pull requests can be merged into your local Git repositories as follows:
 
#* In simple cases, pull requests can be merged into your local Git repositories as follows:
 
#** Add the contributor's Git repository as a remote, e.g. "git remote add <contributor-name> <contributor's repository URL>"
 
#** Add the contributor's Git repository as a remote, e.g. "git remote add <contributor-name> <contributor's repository URL>"
Line 25: Line 57:
 
#** Cherry-pick the commit mentioned in the pull request: "git cherry-pick <hash of commit>"
 
#** Cherry-pick the commit mentioned in the pull request: "git cherry-pick <hash of commit>"
 
#** Confirm that the generated commit has the correct content, and the correct metadata: "git show HEAD", "git log --pretty=full"
 
#** Confirm that the generated commit has the correct content, and the correct metadata: "git show HEAD", "git log --pretty=full"
# Project committer adds a comment on the Bugzilla record that includes URL pointers to the refs in the eclipse.org repository
 
#* e.g., http://git.eclipse.org/c/ecf/org.eclipse.ecf.git/commit/?id=0e184beca9dacdc26ec009dbc54be108a5c5723e
 
# Project committer closes the bug.
 
  
Note that the automated IP Log generator has been updated to include contributions made through Git (see {{bug|327594}}). If Git contributions have the author field correctly set, there is no need to mark the Bugzilla entry iplog+; in fact, doing so may result in redundant entries in the log.
+
=Gerrit=
 +
 
 +
The process changes a bit for projects that use Gerrit Code Review.
 +
 
 +
Assumptions:
 +
* The Contributor is not a project committer;
 +
* A user may have multiple email addresses registered with Gerrit; and
 +
* All of these addresses can be used to identify the user (generally via the Author Email field).
 +
 
 +
Scenario:
 +
 
 +
# If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
 +
#* An Eclipse Foundation account can be created on any of forges managed by the Eclipse Foundation (e.g. [http://projects.eclipse.org projects.eclipse.org], [http://locationtech.org locationtech.org]);
 +
# Contributor creates a Git commit:
 +
#* Author email address must set to the address associated with the author's Eclipse Foundation account;
 +
#* The Contributor must signed-off-by the Contribution, indicating that they are in compliance with the Eclipse Foundation Contributor’s [http://www.eclipse.org/legal/CoO.php Certificate of Origin];
 +
#* The "Signed-off-by" credentials must match the author credentials;
 +
#* Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
 +
#* If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345);
 +
# Contributor pushes their commit to the Gerrit repository;
 +
# Project committer works with contributor to revise (if necessary) the contribution and otherwise shape it into a form that can be accepted by the project;
 +
# Required number of committers approve the commit (this may vary by project);
 +
# Project committer initiates IP Due Diligence process:
 +
#* If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit;
 +
#* Committer waits for check-in;
 +
#* When approved, committer reflects approval on the Gerrit record (i.e. they flip the IP bit on).
 +
# Commit is merged into an appropriate branch by the committer
 +
 
 +
=Bugzilla=
 +
 
 +
An individual (the "Contributor") has attached a patch to a Bugzilla record. A project committer turns that patch into a Git commit.
 +
 
 +
# If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
 +
#* An Eclipse Foundation account can be created on any of forges managed by the Eclipse Foundation (e.g. [http://projects.eclipse.org projects.eclipse.org], [http://locationtech.org locationtech.org]);
 +
#* Committers can [http://projects.eclipse.org/user/cla/validate validate that the contributor has a CLA on file];
 +
# The Contributor must indicate in a bug comment that they are in compliance with the Eclipse Foundation Contributor’s [http://www.eclipse.org/legal/CoO.php Certificate of Origin] (see [[Development Resources/Contributing via Git#Contributing via Bugzilla|Contributing via Bugzilla]]);
 +
# Project committer initiates IP Due Diligence process:
 +
#* If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit; and
 +
#* Committer waits for check-in authorization
 +
# Committer creates a Git commit:
 +
#* The "Author" email address must be set to the address associated with the author's Eclipse Foundation account;
 +
#* The committer enters a "Signed-off-by" line with the contributor's credentials (these must match the value in the "Author" field);
 +
#** A committer should only ever sign-off on a contribution if the contributor has indicated compliance with the Certificate of Origin
 +
#** Make sure the Signed-off-by line is in the ''footer'' of the message, i.e. after the last blank line. See this [[Development_Resources/Contributing_via_Git#Frequently_Asked_Questions|FAQ]].
 +
#* Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
 +
#* Cite the Bugzilla record id in the commit message (e.g. Bug 12345);
 +
# Project committer merges the commit record into one of the project's Git repositories
 +
 
 +
=Multiple Authors=
 +
 
 +
If a contribution has more than one author, additional authors can be indicated by including "Also-by" entries in the commit message. For example:
 +
 
 +
<pre>commit d6cf52411377a039fc2906378711091a26e932cb
 +
Author: Some Body <somebody@somewhere.com>
 +
Date:  Wed May 29 16:17:36 2013 +0200
 +
 
 +
    Hide unwanted common navigator action bar items
 +
   
 +
    This change hides unwanted 'Link with Editor' and 'Customize View...'
 +
    items from the local toolbar and the view menu.
 +
   
 +
    See bug 409722 for restoring the feature of activating the editor when
 +
    changing the selection using 'Link with Selection'.
 +
   
 +
    Bug: 350686
 +
    Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7
 +
    Also-by: Some Bodyelse <somebodyelse@nowhere.com>
 +
    Signed-off-by: Some Body <somebody@somewhere.com></pre>
 +
 
 +
Each of the authors must have a CLA on file. Only the main author needs to sign-off on the commit.
 +
 
 +
=Notes=
 +
 
 +
* The IP Due diligence process permits for certain contributions for work done "under the supervision of the PMC". The definition of "under the supervision of the PMC" varies from PMC to PMC, but is generally accepted to mean that the work is within the scope of the project plan and/or the contribution is a patch for an existing bug/issue.
 +
* A contribution provided through Gerrit does not necessarily have a corresponding record in Bugzilla. If such a record does exist, it should be cited on in the commit message.
 +
* The automated IP Log generator has been updated to include contributions made through Git (see {{bug|327594}}). If Git contributions have the author field correctly set, there is no need to mark the Bugzilla entry iplog+; in fact, doing so may result in redundant entries in the log.
 +
* We require that the contributor explicitly consent to the [http://www.eclipse.org/legal/termsofuse.php Terms of Use] when an account is created.
 +
* Project committers can push commits from contributors. Each individual commit record is subject to the terms outlined above.
 +
* Starting in July 2013, Gerrit will be configured to enforce these requirements.
 +
 
 +
''This page is moderated by the EMO.''
  
[[Category:Git]]
+
[[Category:Git]][[Category:Gerrit]]

Revision as of 10:02, 24 July 2013

This page is directed at Eclipse Committers. If you are not an Eclipse committer but want to contribute to an Eclipse project via Git or Gerrit, please see Contribution via Git.

Contents


Git makes it easy to pull contributions from other repositories and make them part of your own. The natural thing to do in Git is to pull the contribution in question from the contributor's Git repository. Regardless of the mechanism used to actually get the code into an Eclipse project's Git repository, the Eclipse IP Policy and Due Diligence Process must be followed.

One of the main issues that we need to address is that we need to form a connection between code that has been contributed and a statement of provenance, rights, and licensing. You know, lawyer stuff.

For more information, please see Due Diligence Procedures in the Committer Due Diligence Guidelines.

Overview

Contributions received through Git or Gerrit are subject to the following:

  • 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 to Gerrit 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.

Here's some handy boilerplate text that you can use to tell a contributor what they need to do:

Before your contribution can be accepted by the project, you need to create and 
electronically sign the Eclipse Foundation Contributor License Agreement (CLA) and sign 
off on the Eclipse Foundation Certificate of Origin. 

For more information, please visit

http://wiki.eclipse.org/Development_Resources/Contributing_via_Git

Git

An individual (the "Contributor") has forked one of the eclipse.org projects and has issued a pull request for a commit record that they would like to contribute to the eclipse.org project.

  1. If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
  2. Contributor creates a Git commit:
    • Author email address must set to the address associated with the author's Eclipse Foundation account;
    • The Contributor must signed-off-by the Contribution, indicating that they are in compliance with the Eclipse Foundation Contributor’s Certificate of Origin;
    • The "Signed-off-by" credentials must match the author credentials;
    • Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
    • If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345);
  3. Contributor connects with the project via a transparent communication channel (e.g. project mailing list, forum, or Bugzilla record) to indicate that they've authored some code that they'd like to contribute to the project:
    • Contributor provides a link to the contribution's commit for a "Git pull";
  4. Project committer initiates IP Due Diligence process:
    • If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit; and
    • Committer waits for check-in authorization
  5. Project committer merges the commit record into one of the project's Git repositories:
    • In simple cases, pull requests can be merged into your local Git repositories as follows:
      • Add the contributor's Git repository as a remote, e.g. "git remote add <contributor-name> <contributor's repository URL>"
      • Fetch the latest from the contributor's repository: "git fetch <contributor-name>"
      • Cherry-pick the commit mentioned in the pull request: "git cherry-pick <hash of commit>"
      • Confirm that the generated commit has the correct content, and the correct metadata: "git show HEAD", "git log --pretty=full"

Gerrit

The process changes a bit for projects that use Gerrit Code Review.

Assumptions:

  • The Contributor is not a project committer;
  • A user may have multiple email addresses registered with Gerrit; and
  • All of these addresses can be used to identify the user (generally via the Author Email field).

Scenario:

  1. If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
  2. Contributor creates a Git commit:
    • Author email address must set to the address associated with the author's Eclipse Foundation account;
    • The Contributor must signed-off-by the Contribution, indicating that they are in compliance with the Eclipse Foundation Contributor’s Certificate of Origin;
    • The "Signed-off-by" credentials must match the author credentials;
    • Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
    • If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345);
  3. Contributor pushes their commit to the Gerrit repository;
  4. Project committer works with contributor to revise (if necessary) the contribution and otherwise shape it into a form that can be accepted by the project;
  5. Required number of committers approve the commit (this may vary by project);
  6. Project committer initiates IP Due Diligence process:
    • If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit;
    • Committer waits for check-in;
    • When approved, committer reflects approval on the Gerrit record (i.e. they flip the IP bit on).
  7. Commit is merged into an appropriate branch by the committer

Bugzilla

An individual (the "Contributor") has attached a patch to a Bugzilla record. A project committer turns that patch into a Git commit.

  1. If they do not already have one, the Contributor creates an Eclipse Foundation account and signs the Contributor License Agreement
  2. The Contributor must indicate in a bug comment that they are in compliance with the Eclipse Foundation Contributor’s Certificate of Origin (see Contributing via Bugzilla);
  3. Project committer initiates IP Due Diligence process:
    • If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit; and
    • Committer waits for check-in authorization
  4. Committer creates a Git commit:
    • The "Author" email address must be set to the address associated with the author's Eclipse Foundation account;
    • The committer enters a "Signed-off-by" line with the contributor's credentials (these must match the value in the "Author" field);
      • A committer should only ever sign-off on a contribution if the contributor has indicated compliance with the Certificate of Origin
      • Make sure the Signed-off-by line is in the footer of the message, i.e. after the last blank line. See this FAQ.
    • Additional authors may be listed by including "Also-by: {Author Name} <{email}>" entries in the commit comment; and
    • Cite the Bugzilla record id in the commit message (e.g. Bug 12345);
  5. Project committer merges the commit record into one of the project's Git repositories

Multiple Authors

If a contribution has more than one author, additional authors can be indicated by including "Also-by" entries in the commit message. For example:

commit d6cf52411377a039fc2906378711091a26e932cb
Author: Some Body <somebody@somewhere.com>
Date:   Wed May 29 16:17:36 2013 +0200

    Hide unwanted common navigator action bar items
    
    This change hides unwanted 'Link with Editor' and 'Customize View...'
    items from the local toolbar and the view menu.
    
    See bug 409722 for restoring the feature of activating the editor when
    changing the selection using 'Link with Selection'.
    
    Bug: 350686
    Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7
    Also-by: Some Bodyelse <somebodyelse@nowhere.com>
    Signed-off-by: Some Body <somebody@somewhere.com>

Each of the authors must have a CLA on file. Only the main author needs to sign-off on the commit.

Notes

  • The IP Due diligence process permits for certain contributions for work done "under the supervision of the PMC". The definition of "under the supervision of the PMC" varies from PMC to PMC, but is generally accepted to mean that the work is within the scope of the project plan and/or the contribution is a patch for an existing bug/issue.
  • A contribution provided through Gerrit does not necessarily have a corresponding record in Bugzilla. If such a record does exist, it should be cited on in the commit message.
  • The automated IP Log generator has been updated to include contributions made through Git (see bug 327594). If Git contributions have the author field correctly set, there is no need to mark the Bugzilla entry iplog+; in fact, doing so may result in redundant entries in the log.
  • We require that the contributor explicitly consent to the Terms of Use when an account is created.
  • Project committers can push commits from contributors. Each individual commit record is subject to the terms outlined above.
  • Starting in July 2013, Gerrit will be configured to enforce these requirements.

This page is moderated by the EMO.