Add .pt3 support

[talaurence]

I need to add .pt3 support.

[talaurence]

First attempt: write the PT3 support by modifying the functions to decode HT3.

[tritemio]

Great! For reference, more info on adding a new picoquant file in #12.

[tritemio]

I'll write here a getting started guide about using git & github for contributing to phconvert. This is a typical workflow used by many open source projects. The first time there is an "involved" setup step, and it may seem a little daunting, but once you trying a couple of times it becomes easier. Once you have gone through the initial setup, contributing new changes becomes much easier.

1. Fork the project

Login on GitHub, got 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) in 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 YMMV.

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:

Done

Congratulation, configuration completed!

[tritemio]

I found a GitHub help page that explain the same thing: https://help.github.com/articles/fork-a-repo/

[tritemio]

Now, after you have configured the repository you are ready to contribute.

Do the changes

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

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.

[tritemio]

I pasted the above guide to the phconvert wiki: https://github.com/Photon-HDF5/phconvert/wiki/How-to-contribute-on-Github

[tritemio]

This issue is closed by #14