New page under construction (2016-05-25). Bear with me if you see an incomplete version. This page is mainly about documenting the process of linking Apache and Github identities (as people who helped me with it requested I do), but seems an appropriate place to document a few other related things.
A project may seek to benefit from the advantages of both Apache and Github in a best-of-both-worlds scenario integrating the two. This is possible up to a point though with some limitations. Work in progress aims to improve integration and reduce the limitations.
Importing a repo from Github to Apache
An existing repo at Github can be imported to Apache, typically when a project enters incubation. This requires the project to be Apache-licensed, and IP clearance such as a Software Grant should also be in place. The process here is a simple copy: the Github and Apache archives will not be linked. Visitors to the Github pages should be redirected to Apache, and it will often be appropriate for significant individual contributors to become committers to the project at Apache.
To import a repo, submit a ticket to ASFInfra Servicedesk and wait.
Mirroring an Apache git repo at Github
Once your repo is listed at git.apache.org, you can request that it be mirrored at github, where it will now appear at . github.com/apache/$repo-name.git . Github users can now use github facilities, such as forking the repo and contributing via github pull requests. The github mirror will automatically sync to the apache repo, and github notifications will be sent to a nominated project mailinglist at apache. However, this is not (at the time of writing) a full two-way mirror, and the github repos will appear as read-only. Experimental full two-way mirroring is work in progress, involving a small number of volunteering Apache projects but not available to all on-request.
To set up a mirror, submit a ticket to ASFInfra Servicedesk and wait.
Github pull requests
While github pull requests can be submitted and will be propagated to the relevant Apache project list, they cannot be dealt with at github unless your project has full two-way mirroring. They'll have to be committed at apache.
This can be done from the commandline, provided everyone concerned exercises care:
- When submitting a pull request, use a clean branch. It should not contain any local commits other than those included in the pull request.
An Apache committer can merge the pull request into his/her own repo using git pull https : //github.com/user/projectrepo branchname. Be sure you're working in the right branch (typically a clean master or dev branch) with no local commits that might confuse the issue!
Now a git push merges the pull request to the repos at apache and github.
Tip from asfinfra: include a line "Fixes #nnn" in the commit message, and the pull request will be automatically closed at Github.
Linking your Apache and Github identities
If github is to recognise you as an Apache Committer and grant you appropriate privileges, you will need to link your Github and Apache identities (usernames). Apache provides a service for this. The immediate process is self-explanatory, but you will need a few pre-requisites in place or it will leave you stranded for no obvious reason.
This of course assumes you are an Apache Committer and have a Github account. If you're not a committer, this is not for you. If you are an apache committer but don't have a github acount, this is probably of no interest to you, but you can create a Github account and get started.
Join the Apache group at Github
This is initiated when you include your Github username in your Apache details at id.apache.org. Add your Github identity at Apache, and wait for email from Github containing instructions. If you don't receive email (maybe your github ID was already entered at Apache but you didn't join the Apache group at Github at the time), you can also follow through at github.com/apache.
Enable two-factor authentication at Github
This comes under security settings in your Github profile.
Merge All The Things at Apache
Now go to the Apache service at matt.apache.org and complete the three-stage process. It should be self-explanatory, but note that the process is not immediate. Having identified yourself both from Apache and Github, you'll have to wait an hour or two for a batch process to run before it's complete.
When the process is complete, matt.apache.org will show a long list of github mirrors to which it thinks you have access. This may be misleading: you will only have write access to projects with full two-way mirroring. You will receive email from both github and apache confirming your access to such repos.
At the time of writing, an unwanted side-effect is that email originating at github may now be duplicated, coming to you both through your apache project list, and also direct from github, which now knows you as part of the project. Be warned!