Skip to main content
Jump to: navigation, search

Difference between revisions of "Development Resources/Contributing via Git"

m (Fixed name of the link to the CLA)
(The Commit Record: See Bug 558653 Comment 44)
 
(10 intermediate revisions by 5 users not shown)
Line 12: Line 12:
 
* Find a [http://www.polarsys.org/list-of-projects PolarSys project]
 
* Find a [http://www.polarsys.org/list-of-projects PolarSys project]
  
=Eclipse Foundation Contributor License Agreement=
+
=Eclipse Contributor Agreement=
  
Before your contribution can be accepted by the project, you need to create and electronically sign the [http://www.eclipse.org/legal/CLA.php Eclipse Foundation Contributor License Agreement] (CLA).
+
Before your contribution can be accepted by the project, you need to electronically sign the [http://www.eclipse.org/legal/ECA.php Eclipse Contributor Agreement] (ECA).
  
To create a CLA:
+
To sign an ECA:
  
* Create an account with the Eclipse Foundation if you have not already done so;
+
* [https://dev.eclipse.org/site_login/createaccount.php Create an account] with the Eclipse Foundation if you have not already done so;
 
*: An Eclipse Account will grant you access to Gerrit, Bugzilla, and other Eclipse Foundation web resources.
 
*: An Eclipse Account will grant you access to Gerrit, Bugzilla, and other Eclipse Foundation web resources.
 
*: Use the same account to contribute to [http://projects.eclipse.org Eclipse], [http://locationtech.org/projects LocationTech], and [http://polarsys.org PolarSys] projects.
 
*: Use the same account to contribute to [http://projects.eclipse.org Eclipse], [http://locationtech.org/projects LocationTech], and [http://polarsys.org PolarSys] projects.
* Sign a CLA.
+
* Sign a ECA.
** Log into the [https://projects.eclipse.org/user/login/sso Eclipse projects forge];
+
** Log into the [http://www.eclipse.org/contribute/cla Eclipse Contributor Agreement] page;
** Click on "Eclipse CLA"; and
+
 
** Complete the form.
 
** Complete the form.
  
Line 34: Line 33:
 
Minimally, your Git commit record must have the following:
 
Minimally, your Git commit record must have the following:
 
* Your credentials (email address) captured in the "Author" field;  
 
* Your credentials (email address) captured in the "Author" field;  
* A single line summary in the message field, followed by a more detailed descriptive paragraph; and
+
* A single line summary in the message field, followed by a more detailed descriptive paragraph
* A "Signed-off-by" entry with matching credentials in the message footer.
+
  
 
If applicable, a link to the Bug that is addressed by the commit should be included in the message footer. The id (bug number) of the bug should also be included in the message summary.
 
If applicable, a link to the Bug that is addressed by the commit should be included in the message footer. The id (bug number) of the bug should also be included in the message summary.
 +
 +
The email address of the committer must be associated with the Eclipse account with a signed ECA.
  
 
You can specify additional authors using one or more "Also-by" entries in the message footer.
 
You can specify additional authors using one or more "Also-by" entries in the message footer.
Line 55: Line 55:
 
     Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937
 
     Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937
 
     Also-by: Some Otherperson <otherperson@someplace.net>
 
     Also-by: Some Otherperson <otherperson@someplace.net>
    Signed-off-by: Joe Somebody <somebody@someplace.net></pre>
+
</pre>
  
The "Signed-off-by" entry is required. By including this, you confirm that you are in compliance with the [http://www.eclipse.org/legal/CoO.php Certificate of Origin].
+
Note that the footer entries must occur at the bottom of the commit message, must be separated from the summary and description by a blank line, and must not include any blank lines.
 
+
Note that the footer entries must occur at the bottom of the commit message and must not include any blank lines.
+
 
+
==Signing off on a commit==
+
 
+
Both Git and EGit have built-in support for signing off on a commit.
+
 
+
From command-line Git, add -s to the command:
+
 
+
<pre>git commit -s -m "Auto share multiple projects in single job"</pre>
+
 
+
From EGit, there is a handy button in the commit dialog box:
+
 
+
[[Image:Signed-off-by.png]]
+
 
+
EGit can also be configured to sign-off all commits you create from EGit automatically:
+
* click "Preferences > Team > Git > Commit Dialog"
+
* check "Footers > Insert Signed-off-by"
+
  
 
=Contributing a patch=
 
=Contributing a patch=
Line 85: Line 67:
 
A rule with Gerrit is that you should push a '''single commit'''. If you wish to push another version of for an existing Gerrit review, make sure it has the '''same Change-Id''' in commit message footer so Gerrit will understand it as another version and not as a new contribution. The best way to make sure it uses the same Change-Id is to prefer using <tt>git commit --amend</tt> to modify the existing commit and then re-push it.
 
A rule with Gerrit is that you should push a '''single commit'''. If you wish to push another version of for an existing Gerrit review, make sure it has the '''same Change-Id''' in commit message footer so Gerrit will understand it as another version and not as a new contribution. The best way to make sure it uses the same Change-Id is to prefer using <tt>git commit --amend</tt> to modify the existing commit and then re-push it.
  
Then you can simply push new patches to Gerrit using <tt>git push gerrit HEAD:refs/for/master</tt>. It will check CLAs and other stuff, and if you commit gets accepted by this automatic checks, it will return you the URL for your change. Code review and developer interactions will happen on that change. You should receive notifications on each change, but in case you don't, please monitor the change at the given URL to react promptly to questions.
+
Then you can simply push new patches to Gerrit using <tt>git push gerrit HEAD:refs/for/master</tt>. It will check ECAs and other stuff, and if you commit gets accepted by this automatic checks, it will return you the URL for your change. Code review and developer interactions will happen on that change. You should receive notifications on each change, but in case you don't, please monitor the change at the given URL to react promptly to questions.
  
 
Gerrit first contribution FAQ:
 
Gerrit first contribution FAQ:
* '''I have a CLA; why can't I push to Gerrit?''':
+
* '''I have an ECA; why can't I push to Gerrit?''':
 
** First check the email address that you're using on the commit record. It must match the email address you use on your Eclipse Foundation account.
 
** First check the email address that you're using on the commit record. It must match the email address you use on your Eclipse Foundation account.
** We have noticed an issue with Gerrit caching that sometimes introduces latency in the ability for Gerrit to recognize that you have a CLA. This may affect you if you've very recently signed a CLA. Please see {{Bug|407114}}.
+
** We have noticed an issue with Gerrit caching that sometimes introduces latency in the ability for Gerrit to recognize that you have an ECA. This may affect you if you've very recently signed a ECA. Please see {{Bug|407114}}.
* '''The commit is properly signed-off; why is it being rejected?''': The "Signed-off-by" entry must be in the ''footer'' of the commit message. This is the last block of text in the commit message; it cannot contain blank lines. See {{Bug|412140}}. For example, pushing the following commit to Gerrit will fail because the "Signed-off-by" entry is not considered part of the footer (it is separated from the footer by a <span style="background:#FFCCCC">blank line</span>):
+
 
+
commit 862e6ff22ad56c10df6de3385ffa4c7d02363d1d
+
Author: Joe Somebody <somebody@someplace.net>
+
Date:  Mon Jun 17 17:19:38 2013 -0700
+
+
    [410937] Auto share multiple projects in single job
+
   
+
    When multiple projects are imported together, perform all the necessary
+
    auto shares in a single job rather than spawning a separate job for each
+
    project.
+
   
+
    Signed-off-by: Joe Somebody <somebody@someplace.net>
+
<span style="float:left; width:100%; background:#FFCCCC">&zwnj;</span>
+
    Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937
+
    Also-by: Some Otherperson <otherperson@someplace.net>
+
  
 
== via GitHub ==
 
== via GitHub ==
  
If the project repository is hosted on GitHub, you can issue a standard GitHub ''pull'' request. Ensure that you have a CLA and that the commit record is properly "Signed-off-by" before you issue the request.
+
If the project repository is hosted on GitHub, you can issue a standard GitHub ''pull'' request. Ensure that you have a ECA and that the commit record is properly "Signed-off-by" before you issue the request.
 +
 
 +
Some git repos are mirrored to GitHub from the Eclipse Foundation gerrit server. In those cases the contribution needs to be to gerrit rather than via Pull Request. For more information see the [https://projects.eclipse.org/ project's individual developer resources page].
 +
 
 +
[[Image:ContributeViaGit_Mirrored_repo_example.png|example of what a mirrored repo on GitHub looks like]]
 +
 
  
 
== via Bugzilla==
 
== via Bugzilla==
Line 116: Line 87:
 
If you cannot push to a project's Gerrit repository, or do not have a public Git repository from which a project committer can pull, you can submit your contribution as a patch attachment on a Bugzilla record.
 
If you cannot push to a project's Gerrit repository, or do not have a public Git repository from which a project committer can pull, you can submit your contribution as a patch attachment on a Bugzilla record.
  
You must have a signed CLA on file.
+
You must have a signed ECA on file.
 
+
Further, you need to sign-off on the [http://www.eclipse.org/legal/CoO.php Certificate of Origin] in a comment on the bug. For example:
+
This contribution complies with <nowiki>http://www.eclipse.org/legal/CoO.php</nowiki>
+
  
 
=A Word about Eclipse Foundation Accounts=
 
=A Word about Eclipse Foundation Accounts=
  
The Eclipse Foundation maintains multiple separate [[Forges|forges]]. The same user account applies for all forges. If you, for example, create an account on eclipse.org, that same account can be used on [http://locationtech.org LocationTech] or [http://polarsys.org PolarSys]. A signed CLA is connected to your Eclipse Foundation account; this means that with the single valid CLA on file, you can contribute to any project on any of the forges.
+
The Eclipse Foundation maintains multiple separate [[Forges|forges]]. The same user account applies for all forges. If you, for example, create an account on eclipse.org, that same account can be used on [http://locationtech.org LocationTech] or [http://polarsys.org PolarSys]. A signed ECA is connected to your Eclipse Foundation account; this means that with the single valid ECA on file, you can contribute to any project on any of the forges.
  
 
''This page is moderated by the EMO.''
 
''This page is moderated by the EMO.''

Latest revision as of 14:57, 14 May 2021

This page is for individuals who want to make a contribution to an Eclipse project via Git or Gerrit.

There's more information for committers on the Handling Git Contributions page.

Communication

If you want to contribute to an Eclipse project, you should first communicate with that project. Communication takes many forms, but generally occurs on a project's "dev" list, or via Bugzilla.

You can find the appropriate entry points on the project's page on the forge:

Eclipse Contributor Agreement

Before your contribution can be accepted by the project, you need to electronically sign the Eclipse Contributor Agreement (ECA).

To sign an ECA:

Be sure to use the same email address when you register for the account that you intend to use on Git commit records.

The Commit Record

If a project supports Gerrit, you can push directly to that project's repository. Alternatively, if you have a public Git repository, a project committer can pull your contribution.

Minimally, your Git commit record must have the following:

  • Your credentials (email address) captured in the "Author" field;
  • A single line summary in the message field, followed by a more detailed descriptive paragraph

If applicable, a link to the Bug that is addressed by the commit should be included in the message footer. The id (bug number) of the bug should also be included in the message summary.

The email address of the committer must be associated with the Eclipse account with a signed ECA.

You can specify additional authors using one or more "Also-by" entries in the message footer.

For example:

commit 862e6ff22ad56c10df6de3385ffa4c7d02363d1d
Author: Joe Somebody <somebody@someplace.net>
Date:   Mon Jun 17 17:19:38 2013 -0700

    [410937] Auto share multiple projects in single job
    
    When multiple projects are imported together, perform all the necessary
    auto shares in a single job rather than spawning a separate job for each
    project.
    
    Bug: https://bugs.eclipse.org/bugs/show_bug.cgi?id=410937
    Also-by: Some Otherperson <otherperson@someplace.net>

Note that the footer entries must occur at the bottom of the commit message, must be separated from the summary and description by a blank line, and must not include any blank lines.

Contributing a patch

via Gerrit

Many projects have enabled Gerrit to review contributions. When Gerrit is available, it uses a specific repository URL, which should be listed on the contribution page of the project. The general pattern for Gerrit at Eclipse.org URL is ssh://username@git.eclipse.org:29418/path/to/repo.git, so you can add a reference to Gerrit for your repo using git remote add gerrit ssh://username@git.eclipse.org:29418/path/to/repo.git

A rule with Gerrit is that you should push a single commit. If you wish to push another version of for an existing Gerrit review, make sure it has the same Change-Id in commit message footer so Gerrit will understand it as another version and not as a new contribution. The best way to make sure it uses the same Change-Id is to prefer using git commit --amend to modify the existing commit and then re-push it.

Then you can simply push new patches to Gerrit using git push gerrit HEAD:refs/for/master. It will check ECAs and other stuff, and if you commit gets accepted by this automatic checks, it will return you the URL for your change. Code review and developer interactions will happen on that change. You should receive notifications on each change, but in case you don't, please monitor the change at the given URL to react promptly to questions.

Gerrit first contribution FAQ:

  • I have an ECA; why can't I push to Gerrit?:
    • First check the email address that you're using on the commit record. It must match the email address you use on your Eclipse Foundation account.
    • We have noticed an issue with Gerrit caching that sometimes introduces latency in the ability for Gerrit to recognize that you have an ECA. This may affect you if you've very recently signed a ECA. Please see bug 407114.

via GitHub

If the project repository is hosted on GitHub, you can issue a standard GitHub pull request. Ensure that you have a ECA and that the commit record is properly "Signed-off-by" before you issue the request.

Some git repos are mirrored to GitHub from the Eclipse Foundation gerrit server. In those cases the contribution needs to be to gerrit rather than via Pull Request. For more information see the project's individual developer resources page.

example of what a mirrored repo on GitHub looks like


via Bugzilla

If you cannot push to a project's Gerrit repository, or do not have a public Git repository from which a project committer can pull, you can submit your contribution as a patch attachment on a Bugzilla record.

You must have a signed ECA on file.

A Word about Eclipse Foundation Accounts

The Eclipse Foundation maintains multiple separate forges. The same user account applies for all forges. If you, for example, create an account on eclipse.org, that same account can be used on LocationTech or PolarSys. A signed ECA is connected to your Eclipse Foundation account; this means that with the single valid ECA on file, you can contribute to any project on any of the forges.

This page is moderated by the EMO.

Back to the top