Triangular Workflow

This workflow is an adaptation of GitHub triangular workflow.

1. Create a fork of Py-ORBIT.

Press Fork button in Py-ORBIT. Now you have your own copy (fork or clone) of Py-ORBIT repository. This repository is called origin in this guide. The main Py-ORBIT repository is called upstream. So origin is a clone of upstream.

2. Clone your repository to your local computer

In a terminal session on your local computer run following:

git clone https://github.com/<your-GH-username>/py-orbit.git

Now you have a clone of origin on your local computer in py-orbit directory.

3. Setup upstream

You need a way to get modifications that happened upstream, i.e. made by other people.

cd py-orbit
git remote add upstream https://github.com/PyORBIT-Collaboration/py-orbit.git
git remote -v

You should see that you got a new remote called upstream. Now you need a local branch that will track the upstream master.

git fetch upstream
git branch --track upmaster upstream/master
git branch

Now your upmaster branch tracks upstream/master.

4. Create a feature branch and check it out.

git checkout -b new-feature

5. Start developing on this new branch.

Modify code, create more branches as needed etc. When you are done with your development and ready to share make sure that all changes are in your feature branch new-feature.

6. Synchronize local repository with upstream.

You need to check if someone updated upstream while you were developing your new feature.

git checkout upmaster
git fetch upstream
git diff --name-only usptream/master

Will give a list of files that are different in upstream. Merge them in your local repository in branch upmaster (if the list is not empty).

git merge upstream/master

Now your upmaster branch in your local repository has all modifications from upstream. Your local copy has at least three branches:

• upmaster reflects the most recent state of upstream
• new-feature contains your modifications made while developing the new feature.
• master is common ascendant of upmaster and new-feature, it reflects the state of the upstream at the moment you of your fork synchronization with upstream (or when you forked).

7. Test your modifications

While you were developing new feature others probably changed the code as well. So you need to merge your new-feature and upmaster and ensure that the code is still in working condition.

git checkout new-feature 
git merge upmaster

Fix possible conflicts and test the code.

... to be continued ...