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 "Social Coding/Hosting a Project at GitHub"

(Moving Your Existing Project Repositories to GitHub)
(Moving Your Existing Project Repositories to GitHub)
(9 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
=Eclipse Foundation-managed GitHub Organizations=
 
=Eclipse Foundation-managed GitHub Organizations=
  
The Eclipse Foundation manages several organizations on GitHub; one for each of the forges.
+
The Eclipse Foundation manages several organizations on GitHub; one for each of the [[Forges|forges]].
 +
 
 +
*[https://github.com/eclipse Eclipse.org projects on GitHub]
 +
*[https://github.com/locationtech LocationTech.org projects on GitHub]
 +
*[https://github.com/polarsys PolarSys.org projects on GitHub]
 +
 
  
*[https://github.com/eclipse Eclipse on GitHub]
 
*[https://github.com/locationtech LocationTech on GitHub]
 
*[https://github.com/polarsys PolarSys on GitHub]
 
  
 
=Moving Your Existing Project Repositories to GitHub=
 
=Moving Your Existing Project Repositories to GitHub=
Line 11: Line 13:
 
You can move your existing Eclipse Foundation project to GitHub. Don't worry about the history-hiding described below: your Eclipse Foundation project has been developed under the terms of the Eclipse Development Process and the Eclipse IP Due Diligence rules.
 
You can move your existing Eclipse Foundation project to GitHub. Don't worry about the history-hiding described below: your Eclipse Foundation project has been developed under the terms of the Eclipse Development Process and the Eclipse IP Due Diligence rules.
  
Open a request in Bugzilla under the [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Git Community/Git component].
+
Before starting, we suggest you update your [https://dev.eclipse.org/site_login/myaccount.php Eclipse Foundation account] to link it to your GitHub account. This will make several commit, pull request and permissions validations more robust.
 +
 
 +
[[Image:myaccount.png|center|frame|none|Linking a GitHub ID to an Eclipse Foundation account.]]
 +
 
 +
To migrate your project repository(ies) from git.eclipse.org to GitHub:
 +
 
 +
# Talk to your community.  Explain why and when the change will happen.
 +
# Open a request in Bugzilla under the [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Community&component=Git Community/Git component].
 +
# Make sure the Project Lead +1's the request.
 +
# Work with Webmaster to ensure the repository is cloned correctly.
 +
 
 +
Once the repository is on GitHub, nothing changes but the Git URLs.  As committers, you are still expected to follow the Eclipse Development Process, the Committer Guidelines and the IP Due Diligence process.
 +
 
 +
Pull Requests will be examined by web hooks (see below) to ensure the authors have valid CLAs, and that the contribution is Signed-off-by.
  
 
=Moving Your Existing GitHub Project to Eclipse=
 
=Moving Your Existing GitHub Project to Eclipse=
Line 29: Line 44:
 
The timing of the move is important. Once you start this process, you and your existing team will not be able to commit to the repository. As your project committers complete their paperwork, they will be given necessary permissions to work with the repository.
 
The timing of the move is important. Once you start this process, you and your existing team will not be able to commit to the repository. As your project committers complete their paperwork, they will be given necessary permissions to work with the repository.
  
=Moving Existing Repositories=
+
==Moving Existing GitHub Repositories to an Eclipse Foundation Organization==
  
 
Note that the committers listed in your project proposal are permitted to continue working and creating new commits after this process has started. They must follow the Eclipse Foundation's [http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf intellectual property due diligence rules] from the moment we start the move process.
 
Note that the committers listed in your project proposal are permitted to continue working and creating new commits after this process has started. They must follow the Eclipse Foundation's [http://www.eclipse.org/legal/EclipseLegalProcessPoster.pdf intellectual property due diligence rules] from the moment we start the move process.
Line 47: Line 62:
 
As instructed, type the name of the repository, and enter '''eclipsewebmaster''' as the new owner.
 
As instructed, type the name of the repository, and enter '''eclipsewebmaster''' as the new owner.
  
=Collapsing History=
+
==Collapsing History==
  
 
As part of the process of preparing your repository, the Eclipse Webmaster will collapse the history of the project into a single commit. The starting point is the commit identified by the '''eclipse_initial''' tag. The state of the repository represented by that commit is collapsed into a single commit that is then given the '''eclipse_initial''' tag.
 
As part of the process of preparing your repository, the Eclipse Webmaster will collapse the history of the project into a single commit. The starting point is the commit identified by the '''eclipse_initial''' tag. The state of the repository represented by that commit is collapsed into a single commit that is then given the '''eclipse_initial''' tag.
Line 55: Line 70:
 
The existing commits will remain in the repository, but they will not be easily reachable. For more information, please see [[GitHub|Migrating a GitHub Repository]].
 
The existing commits will remain in the repository, but they will not be easily reachable. For more information, please see [[GitHub|Migrating a GitHub Repository]].
  
=Processing Repositories=
+
==Processing Repositories==
  
 
After the project is created, the Eclipse Webmaster will start the provisioning process.  
 
After the project is created, the Eclipse Webmaster will start the provisioning process.  
Line 72: Line 87:
  
 
Some time later, the IP Team will grant full approval. This is a notification to you and the community that initial contribution has completed the due diligence process. Congratulations!
 
Some time later, the IP Team will grant full approval. This is a notification to you and the community that initial contribution has completed the due diligence process. Congratulations!
 +
 +
=GitHub Hooks=
 +
 +
Official project repositories hosted on GitHub must have some "hooks" installed.
 +
 +
The '''Committers hook''' grants designated project committers write access to the GitHub-hosted project repositories. Project committers must use the email address they provide to the Eclipse Foundation as their GitHub email address. Further, that email address must be made publicly accessible (note that we are changing this implementation to instead use GitHub ids directly; see {{Bug|425225}}).
 +
 +
The '''CLA hook''' will inspect incoming GitHub pull requests to ensure that the contributor has a valid CLA.
 +
 +
Project committers should only merge pull "green" requests:
 +
 +
[[File:Github-cla-success.png|Contributors have signed CLAs on file with the Eclipse Foundation.]]
 +
 +
The GitHub API does not give us a means of absolutely denying a merge; all we can do is warn you that the contributors have not signed a CLA:
 +
 +
[[File:Github-cla-failure.png|Not all contributors have signed CLAs on file with the Eclipse Foundation.]]
 +
 +
Do not merge unless you are absolutely certain that the contributer does have a valid CLA on file (e.g. the [https://projects.eclipse.org/user/cla/validate Contributor License Agreement Lookup Tool] confirms that they have a CLA).
 +
 +
Note that you must manually check that the commit message includes the required "Signed-off-by" statement in the footer. See [[Development Resources/Handling Git Contributions|Handling Git Contributions]].
  
 
[[Category:Social Coding]]
 
[[Category:Social Coding]]
 
[[Category:GitHub]]
 
[[Category:GitHub]]

Revision as of 15:01, 18 February 2014

Eclipse Foundation-managed GitHub Organizations

The Eclipse Foundation manages several organizations on GitHub; one for each of the forges.


Moving Your Existing Project Repositories to GitHub

You can move your existing Eclipse Foundation project to GitHub. Don't worry about the history-hiding described below: your Eclipse Foundation project has been developed under the terms of the Eclipse Development Process and the Eclipse IP Due Diligence rules.

Before starting, we suggest you update your Eclipse Foundation account to link it to your GitHub account. This will make several commit, pull request and permissions validations more robust.

Linking a GitHub ID to an Eclipse Foundation account.

To migrate your project repository(ies) from git.eclipse.org to GitHub:

  1. Talk to your community. Explain why and when the change will happen.
  2. Open a request in Bugzilla under the Community/Git component.
  3. Make sure the Project Lead +1's the request.
  4. Work with Webmaster to ensure the repository is cloned correctly.

Once the repository is on GitHub, nothing changes but the Git URLs. As committers, you are still expected to follow the Eclipse Development Process, the Committer Guidelines and the IP Due Diligence process.

Pull Requests will be examined by web hooks (see below) to ensure the authors have valid CLAs, and that the contribution is Signed-off-by.

Moving Your Existing GitHub Project to Eclipse

You will need to engage in the project creation process. Please see Starting a New Project.

When you move your project to Eclipse, all existing related GitHub repositories must be moved into the corresponding GitHub organization. As part of the intellectual property (IP) due diligence process, each repository's history must be collapsed into a single commit that will be used as the project's initial contribution. The complete history will remain in the repository, but it will be obscured to a separate namespace.

  1. Tag your "initial contribution" commit as eclipse_initial
  2. Complete the New Project Provisioning Request (NPPR) form
    You will be sent a link when your project's creation review is complete
    Be sure to select "GitHub" in the "Code Repository" section
  3. Assign ownership of all project-related repositories to eclipsewebmaster
    Wait for the Eclipse Webmaster to take ownership and prepare your repositories
  4. Extract the collapsed history commit (now referenced by the eclipse_initial tag) from each repository as a ZIP file and submit them collectively as your initial contribution

The timing of the move is important. Once you start this process, you and your existing team will not be able to commit to the repository. As your project committers complete their paperwork, they will be given necessary permissions to work with the repository.

Moving Existing GitHub Repositories to an Eclipse Foundation Organization

Note that the committers listed in your project proposal are permitted to continue working and creating new commits after this process has started. They must follow the Eclipse Foundation's intellectual property due diligence rules from the moment we start the move process.

The first step is to assign ownership of the repository to the Eclipse Foundation's Webmaster.

Use the GitHub web interface to transfer ownership of each project repository to eclipsewebmaster.

For each repository, first locate and click the "Settings"; scroll down to the "Danger Zone".

Ride into the "Danger Zone"

Click "Transfer" in the "Transfer Ownership" block.

Assign ownership to Goose the Eclipse Webmaster

As instructed, type the name of the repository, and enter eclipsewebmaster as the new owner.

Collapsing History

As part of the process of preparing your repository, the Eclipse Webmaster will collapse the history of the project into a single commit. The starting point is the commit identified by the eclipse_initial tag. The state of the repository represented by that commit is collapsed into a single commit that is then given the eclipse_initial tag.

That single commit will then be the starting point for all development by the project team following the move to Eclipse. This means that exactly one branch will "survive" the move; be sure to either merge other branches before the move, or get used to the thought of not having them.

The existing commits will remain in the repository, but they will not be easily reachable. For more information, please see Migrating a GitHub Repository.

Processing Repositories

After the project is created, the Eclipse Webmaster will start the provisioning process.

After provisioning is complete, the history of the repository--including all existing commits, branches, and tags--will persist in the repository, but will not be easily accessible (i.e. an average user who clones the repository will not pull in these commits). All of the history will be replaced by a single commit.

GitHubProvisioning2.png

The Eclipse Webmaster will tell you via email when provisioning is complete. At that point in time, extract the initial contribution commit (tagged eclipse_initial as a ZIP file for use as the project's initial contribution.

Project committers can continue to create new commits. From this point forward, committers are expected to follow the Eclipse IP Due Diligence Rules. As committers complete their paperwork and their accounts are provisioned, they will gain the ability to push/merge those commits into the GitHub-based repository. Committers can work in the repository as normal (e.g. they can create branches).

The Eclipse IP Team will review your initial contribution. At some point, the IP team will inform you that the project code has been approved for "Parallel IP Check-in". This is a cue for the Webmaster to start maintaining a mirror of the project repositories on Eclipse Foundation servers. This approval has no direct impact on project developers.

As the IP team works through the due diligence process they may uncover issues that need to be addressed. Be prepared to work with the Eclipse Webmaster to mitigate these issues. In some cases, mitigation may require some "surgery" on the Git repository (e.g. if GPL-licensed code is discovered, it must be completely removed from the accessible history of the repository).

Some time later, the IP Team will grant full approval. This is a notification to you and the community that initial contribution has completed the due diligence process. Congratulations!

GitHub Hooks

Official project repositories hosted on GitHub must have some "hooks" installed.

The Committers hook grants designated project committers write access to the GitHub-hosted project repositories. Project committers must use the email address they provide to the Eclipse Foundation as their GitHub email address. Further, that email address must be made publicly accessible (note that we are changing this implementation to instead use GitHub ids directly; see bug 425225).

The CLA hook will inspect incoming GitHub pull requests to ensure that the contributor has a valid CLA.

Project committers should only merge pull "green" requests:

Contributors have signed CLAs on file with the Eclipse Foundation.

The GitHub API does not give us a means of absolutely denying a merge; all we can do is warn you that the contributors have not signed a CLA:

Not all contributors have signed CLAs on file with the Eclipse Foundation.

Do not merge unless you are absolutely certain that the contributer does have a valid CLA on file (e.g. the Contributor License Agreement Lookup Tool confirms that they have a CLA).

Note that you must manually check that the commit message includes the required "Signed-off-by" statement in the footer. See Handling Git Contributions.

Back to the top