We have recently migrated to git distributed version control (instead of [[CVS]]), as summarised [[git|here]].

−

We are currently testing the benefits of migration to git distributed version control.

+

The process of development of Biopython with git is outlined [[GitUsage|here]].

−

Currently we have a git repository hosted at github.com:

+

This page contains the information on the technicalities of the transition itself and how the core developers should deal with the changes during the transitional period.

−

http://github.com/biopython/biopython/

+

= Current setup =

−

This is the official branch, it's synchronized with the main [[CVS]] trunk every hour, so it should be up to date most of the time.

+

[http://github.com/ GitHub] currently hosts the Biopython Git repository at http://github.com/biopython/biopython/

−

All developers and potential contributors are encouraged to try out this repository.

+

This could become the official repository. Currently it is synchronized with the main [[CVS]] trunk every hour, so it should be up to date most of the time.

−

Below you can find rudimentary instructions on how to develop Biopython with git.

+

== Updates from CVS to github branch ==

−

== Prerequisites ==

+

The updates are done with the [http://cvs2svn.tigris.org/ cvs2svn] tool in the [http://cvs2svn.tigris.org/cvs2git.html cvs2git] mode.

−

=== Installing git ===

+

This works by extracting commits from the cvs repo and generating input for [http://www.kernel.org/pub/software/scm/git/docs/git-fast-import.html git fast-import]. It seems to work nicely and is really fast.

−

First, you need to have git installed on your computer.

+

The updates are performed hourly, using the following configuration [http://bartek.rezolwenta.eu.org/biopython_git_update/].

+

The scripts obtains the cvs repository via rsync and performs the conversion locally. This has to be done this way at least until we get git installed on dev.open-bio.org.

−

Git (http://git-scm.com/) is now available for all major operating systems, you can get it

+

After the conversion is done, the updated git branch is pushed to github, so that others can use it. Afterwards, the copy of the git repo is rsynced back to OBF servers for backup purposes.

−

* Linux: Git is now packaged in all major linux distributions, you should find it in your package manager.

+

−

* Mac OS X: http://code.google.com/p/git-osx-installer/

+

−

* Windows: There are two options: [http://code.google.com/p/msysgit/ MsysGit] or running the compiled git under Cygwin. You can find more information in [http://github.com/guides/using-git-and-github-for-the-windows-for-newbies this github guide]

+

−

=== Getting a github account (Optional) ===

−

Once you have git installed on your machine, you can get the code and start developing,

+

== Accepting code contributions ==

−

However, since the code is hosted at github, you can use more features if you sign up for github account.

+

−

This is completely optional but if you do sign up all other developers will be able to see (and review) the changes you have made.

+

−

If you dan't already have a github account:

+

During the migration, the CVS repo is assumed to be still of higher priority. This means that all code contributions need to go through CVS and then get updated to the github branch. This effectively means, we cannot push to the main biopython branch directly, but instead work on different branches and generate diffs to be applied to CVS.

* Upload an ssh public key by clicking on 'account' after having logged in

+

−

== Obtaining the source code==

+

In case of small bug fixes, the core developers can continue to work directly in CVS. The changes will get pushed to github eventually.

−

If you don't want to make any changes, you can simply download a zipped up archive of the latest code from github. Very easy - and you don't even need to install git on your computer to do this.

+

Since we also want to accept contributions through github, it means that core developer integrating changes will need to do some extra work:

+

* make sure you have an updated version of cvs source tree

+

* make sure you have a git repo with the official and contributed branch

+

* make a diff between the contributed and official branch in git repo (see [[GitUsage]])

+

* apply this diff to the cvs repository

+

* commit in cvs with appropriate message

−

If you want to make changes, then there are two ways of getting the code tree onto your machine. They're not that different, in fact both will result in a directory on your machine containing a full copy of the repository on your machine. However, if you have a github account, you can make your repository a public branch of the project. If you do so, other people will be able to easily review your code, make their own branches from it or merge it back to the trunk.

−

In fact you can change this later, using the .git/config file, but to make it easier I'll describe the two possibilities separately.

+

== Next steps ==

−

=== Forking without a github account ===

+

Once we reach a consensus that git/github serves us well. We will make the final switch. This would include:

−

+

* dropping the cvs support (updating Biopython webpage)

−

Getting a copy of the repository without github account is very simple:

+

* shutting down the cvs2git update scripts

−

+

* installing git on the open-bio servers

−

git clone git://github.com/biopython/biopython.git

+

* setting up a synchronization between obf-hosted branch and github branch

−

+

* posting an announcement on the dev-mailing list, news server, and twitter account to celebrate!

−

This command creates a local copy of the Biopython source on your machine (your own personal branch of the code, with the full history to date). You can now make local changes and commit them to this local copy.

+

−

+

−

However, if you want other people to see your changes you need to take care of publishing your branch yourself. Using github takes care of this for you.

+

−

+

−

=== Forking Biopython using a github account ===

+

−

+

−

If you are logged in to github, you can go to the Biopython repository page

+

−

http://github.com/biopython/biopython/tree/master

+

−

and click on a button named 'Fork'. This will create a fork (basically a copy) of the official Biopython repository, still on publically viewable on github, but listed under your personal account.

+

−

+

−

Now, assuming that you have git installed on your computer, execute the following commands locally on your machine:

+

−

+

−

git clone git@github.com:<your username>/biopython.git

+

−

+

−

Where <your username>, not surprisingly, stands for your github username.

+

−

You have just created a local copy of the biopython repository on your machine.

Now you can make changes to your branch. Since your local branch is a full repository, you can commit your changes as often as you like. In fact, you should commit as often as possible, because smaller commits are much better to manage and document. Let us assume you've made changes to the file Bio/x.py. You need to add this file to your change-set:

+

−

git add Bio/x.py

+

−

and now you commit:

+

−

git commit -m "added feature Y in Bio.x"

+

−

+

−

Your commits in git are local, i.e. they affect only your working branch on your computer, and not the whole Biopython tree or even your fork on github. You don't need an internet connection to commit, so you can do it very often.

+

−

+

−

Once you think your changes are fine and should be reviewed by others, you can push your changes back to the github server:

+

−

git push origin

+

−

+

−

If you think you changes are worth including in the main Biopython distribution, then [http://bugzilla.open-bio.org/ file an (enhancement) bug on Bugzilla], and include a link to your updated branch (i.e. your branch on github, or another public git server). You could also attach a patch on Bugzilla. If the changes are accepted, one of the Biopython developers will have to check this code into our [[CVS]] repository, and within the hour this should update the main Biopython branch on github.

Updates from CVS to github branch

This works by extracting commits from the cvs repo and generating input for git fast-import. It seems to work nicely and is really fast.

The updates are performed hourly, using the following configuration [1].
The scripts obtains the cvs repository via rsync and performs the conversion locally. This has to be done this way at least until we get git installed on dev.open-bio.org.

After the conversion is done, the updated git branch is pushed to github, so that others can use it. Afterwards, the copy of the git repo is rsynced back to OBF servers for backup purposes.

Accepting code contributions

During the migration, the CVS repo is assumed to be still of higher priority. This means that all code contributions need to go through CVS and then get updated to the github branch. This effectively means, we cannot push to the main biopython branch directly, but instead work on different branches and generate diffs to be applied to CVS.

In case of small bug fixes, the core developers can continue to work directly in CVS. The changes will get pushed to github eventually.

Since we also want to accept contributions through github, it means that core developer integrating changes will need to do some extra work:

make sure you have an updated version of cvs source tree

make sure you have a git repo with the official and contributed branch

make a diff between the contributed and official branch in git repo (see GitUsage)

apply this diff to the cvs repository

commit in cvs with appropriate message

Next steps

Once we reach a consensus that git/github serves us well. We will make the final switch. This would include:

dropping the cvs support (updating Biopython webpage)

shutting down the cvs2git update scripts

installing git on the open-bio servers

setting up a synchronization between obf-hosted branch and github branch

posting an announcement on the dev-mailing list, news server, and twitter account to celebrate!