Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Social Coding/Hosting a Project at GitHub
Contents
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.
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 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
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.
- Tag your "initial contribution" commit as eclipse_initial
- Export a snapshot of the "initial contribution" as a ZIP file
- Create an Initial Contribution at attach the ZIP File
- Wait for check-in approval from the IP Team
When you get check-in approval from the IP Team:
- Contact webmaster@eclipse.org to coordinate the move
- Assign ownership of all project-related repositories to eclipsewebmaster
- Wait for the Eclipse Webmaster to take ownership and prepare your repositories
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".
Click "Transfer" in the "Transfer Ownership" block.
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.
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:
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:
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.
Repository Mirrors (Backup)
The Eclipse Webmaster maintains mirrors of all repositories hosted on GitHub (updated hourly). We also take a backup of the issues database in JSON form on a daily basis. If the GitHub repositories become unavailable, the Webmaster team will move the repository mirrors to the forge-specific Git server.