Working on a fork allows you to work on your own copy of phantom, contributing code back to the main code via a “pull request”
How to fork
First, click “Fork this repository” on the main phantom repository in github. You then have your own copy of Phantom in github.com/USERNAME/phantom
How to work on your fork
Clone a copy of your fork onto a local machine:
git clone firstname.lastname@example.org:USERNAME/phantom
push and pull from your fork as you would with the regular phantom repository
How to update your fork with the latest from the main phantom repo
First, make a remote branch that tracks the main repo:
git remote add upstream https://github.com/danieljprice/phantom git fetch upstream
Then every time you want to update, in your forked copy, type:
git checkout master git fetch upstream git merge upstream/master
How to push changes to your fork when you originally cloned the main phantom repo
A common situation is to have checked out a copy from the original repository:
git clone https://github.com/danieljprice/phantom
and you then make some changes to some files, which you commit to the local repo:
cd phantom ...make some amazing code changes... git commit -m 'my amazing code change' file.f90
How should you contribute these back so everyone can benefit? First, you should create your fork as described above. Then you can simply add your new fork as a remote branch of the current repository:
git remote add myfork email@example.com:USERNAME/phantom
Notice that in the above we used the ssh address for github, because you need WRITE permission which is only possible over ssh. If you haven’t already done it, you will need to add your public ssh key to github. To do this go to your .ssh directory:
cd ~/.ssh cat id_rsa.pub ... some long key is printed ...
copy everything that was printed above and paste it into the relevant box under github->settings->SSH and GPG keys, with a name like “my-laptop” or whatever the machine you are currently working on is called. You will need to do this once from every machine you want to push changes from.
If the key exchange was done successfully you should now be able to push your local changes back to your fork:
git push myfork
And finally, you can click the “contribute” button which will create a pull request for your changes to go back to the main phantom repository. Please do this, we are a community code and everyone benefits when you contribute even small things…
I only have a one line change, should I really issue a whole pull request?
Yes, yes and yes. The easiest pull requests to merge are frequent small changes. If you complete an entire PhD worth of work and THEN submit a giant pull request built on changes to a copy of the code you checked out three years ago, it is difficult (but not impossible) to merge. Frequent, small contributions are a much better strategy.
What if I break the code?
That’s why we have a comprehensive test suite that runs on every pull request. Nearly every pull request fails the first time, and requires some tweaking and improvement to pass all of the integration requirements. But this process can only begin once you open your pull request!