Summary

This guide describes how to contribute to a Photon-HDF5 repository (e.g. phconvert) using GitHub. For occasional typo fix to docstrings or documentation you can edit the repository directly online, and you don't need this guide. But, if you plan to do a substantial development, it is better you do it from your local computer as described here.

What I describe is a typical workflow used by many open source projects. For illustration purposes, I'll assume you want to make a contribution to phconvert.

NOTE: The first time there is an "involved" setup, and it may seem a little daunting. Don't despair, once you try a couple of times it becomes easier. Once you have gone through the initial setup, contributing new changes becomes much easier.

Initial Setup

1. Fork the project

Login on GitHub, go to the phconvert repository page and click on the Fork button to "fork" or copy the project under your own username (as opposed to the official version under the Photon-HDF5 organization).

2. Clone your own fork

Cloning means copying the project repository (with full history) on your computer. You can use the git command (from the terminal, i.e. cmd.exe on windows) or you can use a graphical program such as SourceTree or GitHub Desktop (both free). I personally prefer and use SourceTree but GitHub Desktop is fine too. Currently, this guide has screenshots showing how to use SourceTree.

Step 1

On GitHub, go the phconvert repository that you forked under your username. For example, my fork is at https://github.com/tritemio/phconvert (instead of tritemio you will have your user name)

Step 2

Alternative 1: command line

git clone https://github.com/tritemio/phconvert.git

Replace tritemio with your username in the previous command. A new folder containing the phconvert source will be created inside the current folder.

Alternative 2: SourceTree

From SourceTree main window, go to menu New Repository -> Clone from URL fill it like this:

replace tritemio with you own username.

Alternative 3: GitHub Desktop

From your phconvert fork on GitHub click the button to save it to your own computer and use it in GitHub Desktop

Step3: add upstream remote

Your local repo is now linked to your own fork on GitHub. We need to add a "link" to the official repository (under the Photon-HDF5 organization). In git terminology: we add a second remote that will be named upstream.

Alternative 1: command line

From the terminal cd into the phconvert folder, then type:

git remote add upstream https://github.com/Photon-HDF5/phconvert.git

Alternative 2: SourceTree

Open the phconvert repository in SourceTree, then go to the menu Repository -> Repository Setting... -> Remotes and click on Add button. Fill the form as:

Setup finished!

Congratulation, configuration completed!

Contributing

After you have configured the repository you are ready to contribute.

Make the changes locally

Edit the file, for example in spyder, inside your local repository folder. Make sure the editor replaces a TAB with 4 spaces. Also, in spyder, there is an option to trim white-spaces at the end of the line. It is a good idea to enable it.

Test the changes

To test changes is convenient to install phconvert in development mode. In this way, when you type import phconvert you will import the version in your repository (not the conda package).

To do this, open the terminal and cd into the phconvert folder. Then type:

pip install -e .

This will install the package in the current folder in "editable" mode. You need to do this only once. Then from any python session (ipython terminal, notebook, etc...) import phconvert will import your local version.

Commit the changes locally

Saving modifications in the git revision history is called "committing" the changes. From SourceTree, open phconvert repository and click on the Commit button. Select all the files that you want to commit, they will be added to "Staged Files" list. Files in the "Unstaged files" list will not be committed. As an example, a test commit looks like this:

Here I modified pqreader.py adding a comment. I'm committing the changes to pqreader.py but not other files I changed (I can see them in the unstaged list). To finish the commit click Commit.

Push to Github

To publish the changes to your own GitHub repository, click on the button "Push" in SourceTree

Send a Pull Request

When you have a set of changes that are ready for review and incorporation to the official phconvert repository you have to send a Pull Request.

From your phconvert fork on GitHub click on the "New Pull Request" button and follow the instructions.

People can leave comments on the pull request, discuss further changes. Finally, a Photon-HDF5 member can "merge" it to incorporate the modifications in the main repo.