Development workflow¶

Workflow summary¶

• Keep your master branch clean of edits that have not been merged to the main PyTOPKAPI development repo. Your master then will follow the main PyTOPKAPI repository.
• Start a new feature branch for each set of edits that you do.
• If you can avoid it, try not to merge other branches into your feature branch while you are working.
• Ask for review!

This way of working really helps to keep work well organized, and in keeping history as clear as possible.

See - for example - linux git workflow.

Making a new feature branch¶

git branch my-new-feature
git checkout my-new-feature

Generally, you will want to keep this also on your public github fork of PyTOPKAPI. To do this, you git push this new branch up to your github repo. Generally (if you followed the instructions in these pages, and by default), git will have a link to your github repo, called origin. You push up to your own repo on github with:

git push origin my-new-feature

In git >1.7 you can ensure that the link is correctly set by using the --set-upstream option:

git push --set-upstream origin my-new-feature

From now on git will know that my-new-feature is related to the my-new-feature branch in the github repo.

The editing workflow¶

# hack hack
git add my_new_file
git commit -am 'NF - some message'
git push

Asking for code review¶

1. Go to your repo URL - e.g. http://github.com/your-user-name/PyTOPKAPI.

2. Click on the Branch list button:

   

3. Click on the Compare button for your feature branch - here my-new-feature:

   

4. If asked, select the base and comparison branch names you want to compare. Usually these will be master and my-new-feature (where that is your feature branch name).

5. At this point you should get a nice summary of the changes. Copy the URL for this, and post it to the PyTOPKAPI mailing list, asking for review. The URL will look something like: http://github.com/your-user-name/PyTOPKAPI/compare/master...my-new-feature. There’s an example at http://github.com/matthew-brett/nipy/compare/master...find-install-data See: http://github.com/blog/612-introducing-github-compare-view for more detail.

The generated comparison, is between your feature branch my-new-feature, and the place in master from which you branched my-new-feature. In other words, you can keep updating master without interfering with the output from the comparison. More detail? Note the three dots in the URL above (master...my-new-feature) and see Two and three dots in difference specs.

Asking for your changes to be merged with the main repo¶

When you are ready to ask for the merge of your code:

1. Go to the URL of your forked repo, say http://github.com/your-user-name/PyTOPKAPI.git.

2. Click on the ‘Pull request’ button:

   

   Enter a message; we suggest you select only PyTOPKAPI as the recipient. The message will go to the PyTOPKAPI mailing list. Please feel free to add others from the list as you like.

Merging from trunk¶

This updates your code from the upstream PyTOPKAPI github repo.

# go to your master branch
git checkout master
# pull changes from github
git fetch upstream
# merge from upstream
git merge upstream/master

git checkout master

git fetch upstream

git merge upstream/master

Deleting a branch on github¶

git checkout master
# delete branch locally
git branch -D my-unwanted-branch
# delete branch on github
git push origin :my-unwanted-branch

(Note the colon : before test-branch. See also: http://github.com/guides/remove-a-remote-branch

Several people sharing a single repository¶

If you want to work on some stuff with other people, where you are all committing into the same repository, or even the same branch, then just share it via github.

First fork PyTOPKAPI into your account, as from Making your own copy (fork) of PyTOPKAPI.

Then, go to your forked repository github page, say http://github.com/your-user-name/PyTOPKAPI

Click on the ‘Admin’ button, and add anyone else to the repo as a collaborator:

Now all those people can do:

git clone git@githhub.com:your-user-name/PyTOPKAPI.git

Remember that links starting with git@ use the ssh protocol and are read-write; links starting with git:// are read-only.

Your collaborators can then commit directly into that repo with the usual:

git commit -am 'ENH - much better code'
git push origin master # pushes directly into your repo

Exploring your repository¶

To see a graphical representation of the repository branches and commits:

gitk --all

To see a linear list of commits for this branch:

git log

You can also look at the network graph visualizer for your github repo.