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.
Difference between revisions of "Development Resources/Handling Git Contributions"
(New page: 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 th...) |
m (→Gerrit: made the "3 statement" copyable) |
||
| (26 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
| + | __TOC__ | ||
| + | |||
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. | 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. | ||
| − | = | + | 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. | ||
| + | |||
| + | =Git= | ||
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. | 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. | ||
| + | # 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). | ||
| + | #* The developer who authored the code is referred to as the "contributor" or "author" | ||
# Eclipse project committer agrees the contribution is something they would like to include in their project. | # Eclipse project committer agrees the contribution is something they would like to include in their project. | ||
| − | # Contributor or project committer creates a bugzilla that | + | # Contributor (author) or project committer creates a bugzilla that include URL pointers to the refs (commit record) in the source repository. |
| − | # | + | #* e.g., https://github.com/waynebeaton/KittyMunch3/commit/d08bf60f7de9a5e6b48823a115d8054f2a871819 |
| − | # The contributor provides a statement regarding the provenance, rights, and license of the code | + | # The contributor (author) provides a statement regarding the provenance, rights, and license of the code in a comment on the Bugzilla record. |
| − | # If required by the IP Due Diligence Process (e.g. if the contribution exceeds 250 lines), the committer creates a CQ and waits for "check in" permission | + | #* e.g., I assert that I: |
| − | # Project committer merges the pull request back into the eclipse.org project git repository. | + | #*# authored 100% the content they are contributing |
| − | #* | + | #*# have the rights to donate the content to Eclipse |
| + | #*# contribute the content under the EPL | ||
| + | # 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), attaches a patch, and waits for "check in" permission | ||
| + | # 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. | ||
| + | #* 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. | ||
| + | #* 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" | ||
| + | # 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: | |
| + | * 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: | |
| − | # I authored 100% of the | + | # Contributor must create an account on eclipse.org and agree to the Contributor Agreement; |
| − | + | # Contributor creates a Git commit: | |
| − | # | + | #* If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345); and |
| + | #* Author email address is set to a address registered to the author in Gerrit. | ||
| + | # Contributor pushes their commit to the Git/Gerrit repository; | ||
| + | # Contributor asserts on the corresponding bug or in a comment on the Gerrit push record:<blockquote>1. I have authored 100% of the content I'm contributing<br/>2. I have the rights to donate the content to Eclipse<br/>3. I contribute the content under the EPL</blockquote> | ||
| + | # 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 initiated IP Due Diligence process: | ||
| + | #* If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit; | ||
| + | #* Committer records CQ number in the commit message; and | ||
| + | #* 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 | ||
| − | |||
| − | + | 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. | ||
| + | * A this point in time, we require that the contributor explicitly consent to the [http://www.eclipse.org/legal/termsofuse.php Terms of Use] when an account is created; we further require that the contributor assert the three questions ''with each contribution''. Consent can be given either on the Bugzilla record (if one exists), or on a comment connected to the Gerrit push. | ||
| − | + | [[Category:Git]] | |
Revision as of 12:15, 18 June 2012
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.
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 Bug 283749). In the meantime, we have to bridge the old world with the new.
Git
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.
- 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).
- The developer who authored the code is referred to as the "contributor" or "author"
- Eclipse project committer agrees the contribution is something they would like to include in their project.
- Contributor (author) or project committer creates a bugzilla that include URL pointers to the refs (commit record) in the source repository.
- The contributor (author) provides a statement regarding the provenance, rights, and license of the code in a comment on the Bugzilla record.
- e.g., I assert that I:
- authored 100% the content they are contributing
- have the rights to donate the content to Eclipse
- contribute the content under the EPL
- e.g., I assert that I:
- 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), attaches a patch, and waits for "check in" permission
- 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 Committing and Pushing for more information.
- The "Author" name and email in the Git commit record must be set to the contributor's information. See How do I change the author of a commit in git? for help.
- 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"
- Project committer adds a comment on the Bugzilla record that includes URL pointers to the refs in the eclipse.org repository
- 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:
- 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:
- Contributor must create an account on eclipse.org and agree to the Contributor Agreement;
- Contributor creates a Git commit:
- If the contribution is associated with a Bugzilla record, cite that record in the commit message (e.g. Bug 12345); and
- Author email address is set to a address registered to the author in Gerrit.
- Contributor pushes their commit to the Git/Gerrit repository;
- Contributor asserts on the corresponding bug or in a comment on the Gerrit push record:
1. I have authored 100% of the content I'm contributing
2. I have the rights to donate the content to Eclipse
3. I contribute the content under the EPL - 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 initiated IP Due Diligence process:
- If a CQ is required, the committer creates a CQ and attaches a patch generated from the Git commit;
- Committer records CQ number in the commit message; and
- 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
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.
- A this point in time, we require that the contributor explicitly consent to the Terms of Use when an account is created; we further require that the contributor assert the three questions with each contribution. Consent can be given either on the Bugzilla record (if one exists), or on a comment connected to the Gerrit push.