source/chapters/contributing.adoc - gerrit/dash/org.eclipse.dash.handbook - Git at Google

 ////
  * Copyright (C) Eclipse Foundation, Inc. and others.
  *
  * This program and the accompanying materials are made available under the
  * terms of the Eclipse Public License v. 2.0 which is available at
  * http://www.eclipse.org/legal/epl-2.0.
  *
  * SPDX-License-Identifier: EPL-2.0
 ////

 [[contributing]]
 = Contributing to {aForge} Projects

 [[contributing-contributors]]
 == Contributors

 Anybody can be a contributor. To be a contributor, you need to contribute. Contributions typically take the form of code or documentation submitted to the project's source code repository, but may also take the form of answering questions in project and community forums, and more.

 For contributions that contain intellectual property (e.g., source code or documentation), some formal documentation is required to ensure that the rights assoicated with the intellectual property are properly attributed and licensed.

 To contribute intellectual property, you need to:

 . Create an <<contributing-account,Eclipse Foundation Account>>;
 . Sign the <<resources-eca,Eclipse Contributor Agreement>>;
 . Read the project's contribution guide to learn about coding style and other guidelines for contributions (contribution guidelines are typically found a `CONTRIBUTING` or `README` file in the root of every source code repository)
 . Create a pull request (GitHub), or submit a review (Gerrit):
 .* Ensure that the author credentials match the email address associated with your Eclipse Foundation Account, and
 .* Ensure that all commits have been _Signed-off_;
 . Work with the project team to merge your contribution.

 Note that contributors retain ownership of their contributions; the ECA, for example, states in part:

 ____
 This ECA, and the license(s) associated with the particular Eclipse Foundation projects You are contributing to, provides a license to Your Contributions to the Eclipse Foundation and downstream consumers, but *You still own Your Contributions*, and except for the licenses provided for in this ECA, You reserve all right, title and interest in Your Contributions.
 ____

 That is, the contributor owns their contributions, but grants a license to the Eclipse Foundation and downstream consumers to use them under the terms of the project license.

 == Committers

 For Eclipse Projects (and the open source world in general), committers are ones who hold they keys. Committers decide what code goes into the code base, they decide how a project builds, and they ultimately decide what gets delivered to the adopter community. With awesome power, comes awesome responsibility, and so the Open Source Rules of Engagement described by the {edpUrl}[Eclipse Foundation Development Process], puts _meritocracy_ on equal footing with _transparency_ and _openness_: becoming a committer isn’t necessarily hard, but it does require a demonstration of merit.

 In practical terms, there are two ways to become an Eclipse Committer.

 The first way is to be listed as an initial committer on a new <<starting-proposal,project proposal>>. When projects come to the Eclipse Foundation we need them to actually start with committers, and so we include this as part of the bootstrapping. As part of the process of community vetting a new project proposal, the committers listed are themselves vetted by the community. In effect, the project proposal process also acts as a committer election that’s open to the entire community.

 The second way to become a committer is to get voted in via <<elections-committer,committer election>. After an individual has made a small number of high quality contributions that demonstrate that they understand how the project works, understand the Eclipse Development Process and are prepared to implement the Eclipse IP Policy, a committer will invite them to join the team and initate the election. Comitter elections start with a nomination by an existing committer that includes a statement of merit that usually takes the form of a list various contributions that the individual has made to the project. What constitutes a sufficient demonstration of merit varies by project team and  team.

 [NOTE]
 ====
 Committer status is assigned on a project-by-project basis. That is, individuals have committer rights only on those projects for which they hold committer status. For all other projects, they are contributors.
 ====

 When a contributor becomes a committer, they must be convered by a committer agreement (either a {mccaUrl}[Member Committer and Contributor Agreement] (MCCA) or an {icaUrl}[Individual Committer Agreement] (ICA). As the last step in the committer election process, the Eclipse Foundation systems will determine which agreement applies and engage a workflow with the new committer to ensure that everything is in place.

 == Eclipse Account

 Eclipse Foundation project resources are generally accessible without an acccount. That is, members of the community may browse code, documentation, issues, help, etc. without creating an Eclipse Foundation Account. For those members of the community that wish to contribute code patches, open issues, add content to wikis, etc., an {accountUrl}[Eclipse Foundation Account] is required.

 For contributors and committers, their Eclipse Foundation account is their primary portal into their relationship with the Eclipse Foundation. From their account page, individuals can sign the {ecaUrl}[Eclipse Contributor Agreement], manage their mailing list subscriptions, access build resources, and more.

 [TIP]
 ====
 If you're working with projects that use GitHub, be sure to add your GitHub Id to your Eclipse Foundation Account so that our scripts can add you to the GitHub Teams that we use to manage access to Eclipse Foundation repositories hosted on GitHub. When, for exmaple, you become a committer on an Eclipse project that hosts their source code repositories on GitHub, you will be sent an invitation to join the GitHub Team associated with that project.
 ====

 [[resources-eca]]
 == Eclipse Contributor Agreement (ECA)

 All contributors, who are not committers on the {forgeName} project, must sign the {ecaUrl}[Eclipse Contributor Agreements] (ECA) to ensure that the necessary <<ip,intellectual property>> (IP) rights to the contribution are granted.

 Contributors who are already covered by a committer agreement (either an MCCA or ICA) are not required to also sign the ECA.

 [TIP]
 ====
 You can determine your ECA status from your {accountUrl}[Eclipse Foundation Account page]. Your ECA status is shown in the top-right corner.
 ====

 Committers *do not* require an ECA to contribute to a project on which they have committer status.

 [[resources-commit]]
 === Git Commit Records

 Git commit records are required to take a specific form. The credentials of the actual author must be used to populate the `Author` field. The author credentials must specify the author's actual (legal) name and email address. The email address used must match the email address that the Eclipse Foundation has on file for the author (case-sensitive).

 The commit message is divided into three sections:

 . One line (max 72 characters) summary;
 . Description; and
 . Footer.

 .Example Git Commit Record
 [source]
 ------------------------------------------------------------
 commit d6cf52411377a039fc2906378711091a26e932cb
 Author: Some Body <somebody@somewhere.com> <1>
 Date:   Wed May 29 16:17:36 2013 +0200

     Bug 350686 - Hide unwanted action bar items <2>

     This change hides unwanted 'Link with Editor' and
     'Customize View...' items from the local toolbar
     and the view menu.

     Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 <3>
     Also-by: Some Bodyelse <somebodyelse@nowhere.com> <4>
     Signed-off-by: Some Body <somebody@somewhere.com> <5>
 ------------------------------------------------------------

 <1> The email address of the author must match the email address on the Eclipse Foundation Account, the name "Some Body" must be replaced by the real name of the person.
 <2> Best practice: include the bug id in the commit message summary.
 <3> Gerrit `Change-Id` (only when pushing to Gerrit for review).
 <4> Additional authors can be added using `Also-by` or `Co-authored-by` entries, by replacing the name "Some Bodyelse" by the real name of the person
 <5> Non-committers must _sign-off_ the commit, indicating that they aware of the terms by which the contribution has been provided to the project, using the same name and email address as used in the author field.

 [IMPORTANT]
 ====
 The named used in the `Author` field (and, when required, in the `Also-by` and `Signed-off-by` fields) must be the legal name of the contributor; the email address must be valid and real.
 ====

 The _summary_ line is used in many places where Git commits are listed, ensure that this line is sensible by itself. The _description_ area should be used to provide more detail about the commit. The footer area is used for extra fields and values.

 If the bug id is included in the summary line (using the form "Bug 12345 - xxx" or "[12345] xxx") Gerrit Code Review will automatically add a link in the corresponding Bugzilla record back to the Gerrit record (this, of course, only applies to commits pushed to Gerrit).

 The `Change-Id` is used by <<resources-gerrit,Gerrit Code Review>> to associate new versions of a change back to its original review. This field need only be specified if the repository is managed by Gerrit.

 An `Also-by` (or `Co-authored-by`) entry can be added for each additional author of a commit (one committer per entry). This might apply, for example, if a commit has been authored via pair-programming, or the commit is the result of collapsing multiple commits authored by multiple developers. To be considered valid the entry must take the form `Also-by: Name <email>`.

 Commits that are provided by non-committers must have a `Signed-off-by` field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. To be considered valid the entry must take the form `Signed-off-by: Name <email>`. The non-committer must additionally have an Eclipse Foundation Account and must have a signed <<resources-eca,Eclipse Contributor Agreement>> (ECA) on file.

 [[contributing-faq]]
 == Frequently Asked Questions

 [qanda]
 Is there any requirement on what is necessary for committers/project leads to consider when dealing with contributions from someone from the same company? ::

 No requirement. Getting reviews/approvals from any committer on your project is sufficient, whether they are from the same company or different.
 +
 Project teams may establish their own rules regarding how contributions are accepted. These rules range from allowing any committer to approve a contribution, to requiring that contributions from a committer be approved by another committer, to requiring that all contributions be approved by a project lead. Whatever the case, it should be documented (typically captured in a `CONTRIBUTING` file).
 +
 It is generally considered good practice (or a nice-to-have) to request a review from an "outsider", especially if the proposed change might be considered complex or controversial.  It's always good to get outside viewpoints. But the specific rules are left for the project team to decide.
	////
	* Copyright (C) Eclipse Foundation, Inc. and others.
	*
	* This program and the accompanying materials are made available under the
	* terms of the Eclipse Public License v. 2.0 which is available at
	* http://www.eclipse.org/legal/epl-2.0.
	*
	* SPDX-License-Identifier: EPL-2.0
	////

	[[contributing]]
	= Contributing to {aForge} Projects

	[[contributing-contributors]]
	== Contributors

	Anybody can be a contributor. To be a contributor, you need to contribute. Contributions typically take the form of code or documentation submitted to the project's source code repository, but may also take the form of answering questions in project and community forums, and more.

	For contributions that contain intellectual property (e.g., source code or documentation), some formal documentation is required to ensure that the rights assoicated with the intellectual property are properly attributed and licensed.

	To contribute intellectual property, you need to:

	. Create an <<contributing-account,Eclipse Foundation Account>>;
	. Sign the <<resources-eca,Eclipse Contributor Agreement>>;
	. Read the project's contribution guide to learn about coding style and other guidelines for contributions (contribution guidelines are typically found a `CONTRIBUTING` or `README` file in the root of every source code repository)
	. Create a pull request (GitHub), or submit a review (Gerrit):
	.* Ensure that the author credentials match the email address associated with your Eclipse Foundation Account, and
	.* Ensure that all commits have been _Signed-off_;
	. Work with the project team to merge your contribution.

	Note that contributors retain ownership of their contributions; the ECA, for example, states in part:

	____
	This ECA, and the license(s) associated with the particular Eclipse Foundation projects You are contributing to, provides a license to Your Contributions to the Eclipse Foundation and downstream consumers, but You still own Your Contributions, and except for the licenses provided for in this ECA, You reserve all right, title and interest in Your Contributions.
	____

	That is, the contributor owns their contributions, but grants a license to the Eclipse Foundation and downstream consumers to use them under the terms of the project license.

	== Committers

	For Eclipse Projects (and the open source world in general), committers are ones who hold they keys. Committers decide what code goes into the code base, they decide how a project builds, and they ultimately decide what gets delivered to the adopter community. With awesome power, comes awesome responsibility, and so the Open Source Rules of Engagement described by the {edpUrl}[Eclipse Foundation Development Process], puts _meritocracy_ on equal footing with _transparency_ and _openness_: becoming a committer isn’t necessarily hard, but it does require a demonstration of merit.

	In practical terms, there are two ways to become an Eclipse Committer.

	The first way is to be listed as an initial committer on a new <<starting-proposal,project proposal>>. When projects come to the Eclipse Foundation we need them to actually start with committers, and so we include this as part of the bootstrapping. As part of the process of community vetting a new project proposal, the committers listed are themselves vetted by the community. In effect, the project proposal process also acts as a committer election that’s open to the entire community.

	The second way to become a committer is to get voted in via <<elections-committer,committer election>. After an individual has made a small number of high quality contributions that demonstrate that they understand how the project works, understand the Eclipse Development Process and are prepared to implement the Eclipse IP Policy, a committer will invite them to join the team and initate the election. Comitter elections start with a nomination by an existing committer that includes a statement of merit that usually takes the form of a list various contributions that the individual has made to the project. What constitutes a sufficient demonstration of merit varies by project team and team.

	[NOTE]
	====
	Committer status is assigned on a project-by-project basis. That is, individuals have committer rights only on those projects for which they hold committer status. For all other projects, they are contributors.
	====

	When a contributor becomes a committer, they must be convered by a committer agreement (either a {mccaUrl}[Member Committer and Contributor Agreement] (MCCA) or an {icaUrl}[Individual Committer Agreement] (ICA). As the last step in the committer election process, the Eclipse Foundation systems will determine which agreement applies and engage a workflow with the new committer to ensure that everything is in place.

	== Eclipse Account

	Eclipse Foundation project resources are generally accessible without an acccount. That is, members of the community may browse code, documentation, issues, help, etc. without creating an Eclipse Foundation Account. For those members of the community that wish to contribute code patches, open issues, add content to wikis, etc., an {accountUrl}[Eclipse Foundation Account] is required.

	For contributors and committers, their Eclipse Foundation account is their primary portal into their relationship with the Eclipse Foundation. From their account page, individuals can sign the {ecaUrl}[Eclipse Contributor Agreement], manage their mailing list subscriptions, access build resources, and more.

	[TIP]
	====
	If you're working with projects that use GitHub, be sure to add your GitHub Id to your Eclipse Foundation Account so that our scripts can add you to the GitHub Teams that we use to manage access to Eclipse Foundation repositories hosted on GitHub. When, for exmaple, you become a committer on an Eclipse project that hosts their source code repositories on GitHub, you will be sent an invitation to join the GitHub Team associated with that project.
	====

	[[resources-eca]]
	== Eclipse Contributor Agreement (ECA)

	All contributors, who are not committers on the {forgeName} project, must sign the {ecaUrl}[Eclipse Contributor Agreements] (ECA) to ensure that the necessary <<ip,intellectual property>> (IP) rights to the contribution are granted.

	Contributors who are already covered by a committer agreement (either an MCCA or ICA) are not required to also sign the ECA.

	[TIP]
	====
	You can determine your ECA status from your {accountUrl}[Eclipse Foundation Account page]. Your ECA status is shown in the top-right corner.
	====

	Committers do not require an ECA to contribute to a project on which they have committer status.

	[[resources-commit]]
	=== Git Commit Records

	Git commit records are required to take a specific form. The credentials of the actual author must be used to populate the `Author` field. The author credentials must specify the author's actual (legal) name and email address. The email address used must match the email address that the Eclipse Foundation has on file for the author (case-sensitive).

	The commit message is divided into three sections:

	. One line (max 72 characters) summary;
	. Description; and
	. Footer.

	.Example Git Commit Record
	[source]
	------------------------------------------------------------
	commit d6cf52411377a039fc2906378711091a26e932cb
	Author: Some Body <somebody@somewhere.com> <1>
	Date: Wed May 29 16:17:36 2013 +0200

	Bug 350686 - Hide unwanted action bar items <2>

	This change hides unwanted 'Link with Editor' and
	'Customize View...' items from the local toolbar
	and the view menu.

	Change-Id: Ia2bd5091303d1b0a738157effc24e4dac5a7d0c7 <3>
	Also-by: Some Bodyelse <somebodyelse@nowhere.com> <4>
	Signed-off-by: Some Body <somebody@somewhere.com> <5>
	------------------------------------------------------------

	<1> The email address of the author must match the email address on the Eclipse Foundation Account, the name "Some Body" must be replaced by the real name of the person.
	<2> Best practice: include the bug id in the commit message summary.
	<3> Gerrit `Change-Id` (only when pushing to Gerrit for review).
	<4> Additional authors can be added using `Also-by` or `Co-authored-by` entries, by replacing the name "Some Bodyelse" by the real name of the person
	<5> Non-committers must _sign-off_ the commit, indicating that they aware of the terms by which the contribution has been provided to the project, using the same name and email address as used in the author field.

	[IMPORTANT]
	====
	The named used in the `Author` field (and, when required, in the `Also-by` and `Signed-off-by` fields) must be the legal name of the contributor; the email address must be valid and real.
	====

	The _summary_ line is used in many places where Git commits are listed, ensure that this line is sensible by itself. The _description_ area should be used to provide more detail about the commit. The footer area is used for extra fields and values.

	If the bug id is included in the summary line (using the form "Bug 12345 - xxx" or "[12345] xxx") Gerrit Code Review will automatically add a link in the corresponding Bugzilla record back to the Gerrit record (this, of course, only applies to commits pushed to Gerrit).

	The `Change-Id` is used by <<resources-gerrit,Gerrit Code Review>> to associate new versions of a change back to its original review. This field need only be specified if the repository is managed by Gerrit.

	An `Also-by` (or `Co-authored-by`) entry can be added for each additional author of a commit (one committer per entry). This might apply, for example, if a commit has been authored via pair-programming, or the commit is the result of collapsing multiple commits authored by multiple developers. To be considered valid the entry must take the form `Also-by: Name <email>`.

	Commits that are provided by non-committers must have a `Signed-off-by` field in the footer indicating that the author is aware of the terms by which the contribution has been provided to the project. To be considered valid the entry must take the form `Signed-off-by: Name <email>`. The non-committer must additionally have an Eclipse Foundation Account and must have a signed <<resources-eca,Eclipse Contributor Agreement>> (ECA) on file.

	[[contributing-faq]]
	== Frequently Asked Questions

	[qanda]
	Is there any requirement on what is necessary for committers/project leads to consider when dealing with contributions from someone from the same company? ::

	No requirement. Getting reviews/approvals from any committer on your project is sufficient, whether they are from the same company or different.
	+
	Project teams may establish their own rules regarding how contributions are accepted. These rules range from allowing any committer to approve a contribution, to requiring that contributions from a committer be approved by another committer, to requiring that all contributions be approved by a project lead. Whatever the case, it should be documented (typically captured in a `CONTRIBUTING` file).
	+
	It is generally considered good practice (or a nice-to-have) to request a review from an "outsider", especially if the proposed change might be considered complex or controversial. It's always good to get outside viewpoints. But the specific rules are left for the project team to decide.