ooici on GitHub will be our new reference code repoistory.
We will be making a switch over from Amoeba (gitosis) to GitHub for following code repositories/branches:
- lcaarch -> ioncore-python (master, develop)
- ion-proto-umbrella -> ion-object-definitions (master)
- ioncore-java (master, develop)
- ooici-pres (master)
- Create a free GitHub ID, if you don't already have one, at github.com.
- Upload your SSH public key (located at ~/.ssh/id_dsa.pub) following instructions on GitHub, if you have not done so.
- Send your GitHub ID to Jamie (jachen) so you will be added as a collaborator to ooici source code repositories on GitHub.
- ITV will notify the team to check in all code to Ameoba COB before a switch-over date.
- ITV will make Amoeba code respositories read-only on switch-over date.
- ITV will update GitHub with code in Amoeba and notify development team that GitHub is ready for access.
GitHub easily allows a developer to stand up code repositories. Since you could be pulling code from multiple repositories, it's best to adopt a naming convention for your git remotes to avoid confusion later.
Start fresh by cloning ioncore-python repository from gitHub:
Rename remote 'origin' to 'ooici' to be explicit.
Add remote 'amoeba' in case you need to fetch existing topics from 'amoeba':
If you need to pull code from another developer's public GitHub repository (See Collaboration Workflow), create a remote name that matches the GitHub ID for easy identification.
|Optional Alternative: Configure Remotes for Existing Code|
Alternatively, you can point your existing repoistory to ooici gitHub.
Find out remote names for your existing Git repository:
Amoeba git repository should be called 'amoeba' to avoid confusion. Most likely, it's called 'origin'. Here is how to rename it:
Create a remote that points to ooici gitHub:
If you are collaborating on a topic branch on jdoe's GitHub (or, you are jdoe and you just forked 'ioncore-python' from 'ooici' GitHub), add this remote:
If you have branches that are tracking branches on Ameoba, and you want to update them to track new remotes, use this:
This can be used regardless of which branch you are currently on in your working copy. If it's a topic branch that you are going to have in your personal github location, you have to push it to that remote before you can change your local branch's tracking.
For more info, see this stackoverflow question.
For those of you who have an existing topic branch (other than 'develop' and 'master') on Amoeba that were not migrated to ooici GitHub, you will still have read only access to those branches on 'Amoeba'. Here's how you can migrate that branch to your own GitHub and continue collaboration with your fellow developers.
- Make sure your remotes are configured correctly for your existing project. See instruction here.
- To migrate this topic branch from Amoeba to your GitHub, follow the Collaboration Workflow. The only change is step 3.
Change to Collaboration Workflow Step 3
John obtains an existing topic 'topic1' from amoeba and pushes that topic to his GitHub repository 'jdoe'.
- Each 'ooici' GitHub code repository shall contain only two branches ('develop' for unstable and 'master' for stable).
- Always create a topic branch when doing development instead of working off 'develop' directly. It's cheap to create a branch. It's easy to merge to 'develop' after your topic is done.
- Create topic branch only in your local repository and your GitHub, not on 'ooici' GitHub.
Some developers use 'git pull'. 'git pull' != 'git fetch'. 'git pull' = 'git fetch' + 'git merge'. It's best to be explicit.
- Paul fetches from ooici GitHub to get most recent updates on all remote branches.
- Paul works in his local repository by creating a topic branch off 'develop', e.g., 'topic1'.
- Paul merges his work back into 'develop' and pushes to ooici:
Two or more developers need to collaborate on a feature.
Lead developer John wants to adopt a model where Paul can push work to John's GitHub repository. He could alternatively use fork-and-pull model with Paul, which is not discussed here.
- Lead developer John creates a fork from 'ooici/ioncore-python' to his GitHub repository 'jdoe/ioncore-python'. (Using GitHub Web GUI. See help here)
- John adds Paul's GitHub ID as a collaborator to his forked project 'jdoe/ioncore-python'. (Using GitHub Web GUI)
- John creates a topic branch 'topic1' in his local repository and pushes that topic to 'jdoe'.
- Support developer Paul fetches from 'jdoe' to add his work.
- John can now fetch from 'jdoe' GitHub repository to get Paul's updates on 'topic1', and collaborate some more, etc., etc.
- After all is said and done, it's time to merge 'jdoe/topic1' back to 'ooici/develop' on GitHub.
Scenario 1: Lead Merges Work
In this scenario, John wants to take charge in merging to 'ooici/develop' on GitHub.
|Scenario 2: Lead sends a pull request & ITV Merges Work|
This scenario is useful when you want your changes submitted to 'ooici' explicitly. You can request code reviews and initiate further discussions on the work done in this case.
When you have a branch that's been merged or no longer needed, it's time to clean it up:
If you find yourself tracking/working on branches with the same name from different remotes (forks on github), you are free to name them in whatever fashion best suits your memory.
When pushing, you must take care not to push your locally named branch to github.
In this case, there is an ooici-dm remote, which I have a local branch named "develop-dm" tracking its develop branch. When I want to push it back to ooici-dm/develop, I use the command
If you find yourself pushing a wrongly named branch, use the push syntax from the Housekeeping section above where there is no local ref to the left of the colon. This deletes the remote