GitMigration

(Difference between revisions)
Jump to: navigation, search
(Re-organizing to have one fewer levels of headers.)
m (Git and GitHub capitalization corrections.)
Line 1: Line 1:
We are currently testing the benefits of migration to git distributed version control.
+
We are currently testing the benefits of migration to Git distributed version control.
  
Currently we have a git repository hosted at github.com:
+
[http://github.com/ GitHub] currently hosts the Biopython Git repository at http://github.com/biopython/biopython/
  
http://github.com/biopython/biopython/
+
This is 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. All developers and potential contributors are encouraged to try out this repository. Instructions on developing Biopython with Git follow below.
 
+
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.
+
 
+
All developers and potential contributors are encouraged to try out this repository.  
+
 
+
Below you can find rudimentary instructions on how to develop Biopython with git.
+
  
 
= Prerequisites =
 
= Prerequisites =
  
== Installing git ==
+
== Installing Git ==
  
First, you need to have git installed on your computer.  
+
First, you need to have Git installed on your computer.  
  
 
Git (http://git-scm.com/) is now available for all major operating systems.
 
Git (http://git-scm.com/) is now available for all major operating systems.
Line 40: Line 34:
 
==== msysGit (Recommended) ====
 
==== msysGit (Recommended) ====
  
[http://code.google.com/p/msysgit/ msysGit] is a port of Git that runs natively on Windows via the MinGW library. Because Git was not originally designed to run on Windows, and since this is a port, some bugs exist, though are rarely encountered in everyday use of Git. See their website for download and installation instructions. Additionally, you can watch [http://gitcasts.com/posts/git-on-windows Scott Chacon's screencast on installing msysGit on Windows], and see [http://github.com/guides/using-git-and-github-for-the-windows-for-newbies this github guide].
+
[http://code.google.com/p/msysgit/ msysGit] is a port of Git that runs natively on Windows via the MinGW library. Because Git was not originally designed to run on Windows, and since this is a port, some bugs exist, though are rarely encountered in everyday use of Git. See their website for download and installation instructions. Additionally, you can watch [http://gitcasts.com/posts/git-on-windows Scott Chacon's screencast on installing msysGit on Windows], and see [http://github.com/guides/using-git-and-github-for-the-windows-for-newbies this GitHub guide].
  
 
==== Cygwin ====
 
==== Cygwin ====
Line 46: Line 40:
 
[http://www.cygwin.com/ Cygwin] provides a Linux-like environment for Windows. It includes access to repositories of many software packages available commonly in Linux distributions, including Git. You can find the <tt>git</tt> package under the "devel" category.
 
[http://www.cygwin.com/ Cygwin] provides a Linux-like environment for Windows. It includes access to repositories of many software packages available commonly in Linux distributions, including Git. You can find the <tt>git</tt> package under the "devel" category.
  
== Getting a github account (Optional) ==
+
== Getting a GitHub account (Optional) ==
  
Once you have git installed on your machine, you can get the code and start developing,
+
Once you have Git installed on your machine, you can get the code and start developing,
However, since the code is hosted at github, you can use more features if you sign up for github account.  
+
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.  
 
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:
+
If you dan't already have a GitHub account:
 
* create one here http://github.com/plans (the free plan is absolutely enough)
 
* create one here http://github.com/plans (the free plan is absolutely enough)
 
* Upload an ssh public key by clicking on 'account' after having logged in  
 
* Upload an ssh public key by clicking on 'account' after having logged in  
Line 58: Line 52:
 
= Obtaining the source code=
 
= Obtaining the source code=
  
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.
+
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.
 
In fact you can change this later, using the .git/config file, but to make it easier I'll describe the two possibilities separately.
  
== Forking without a github account ==
+
== Forking without a GitHub account ==
  
Getting a copy of the repository without github account is very simple:
+
Getting a copy of the repository without GitHub account is very simple:
 
   
 
   
 
   git clone git://github.com/biopython/biopython.git
 
   git clone git://github.com/biopython/biopython.git
Line 70: Line 64:
 
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.
 
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.
+
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 ==
+
== Forking Biopython using a GitHub account ==
  
If you are logged in to github, you can go to the Biopython repository page
+
If you are logged in to GitHub, you can go to the Biopython repository page
 
  http://github.com/biopython/biopython/tree/master
 
  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.
+
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:
+
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
 
  git clone git@github.com:<your username>/biopython.git
  
Where <your username>, not surprisingly, stands for your github username.
+
Where <your username>, not surprisingly, stands for your GitHub username.
 
You have just created a local copy of the biopython repository on your machine.
 
You have just created a local copy of the biopython repository on your machine.
  
Line 101: Line 95:
 
  git commit -m "added feature Y in Bio.x"
 
  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.  
+
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:
+
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
 
  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.
+
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.
  
On GitHub itself, you can inform keepers of the main branch of your changes by sending a 'pull request' from the main page of your branch. Once the file has been committed to the main branch, you may want to delete your now redundant bug fix branch on github.  Branches can be deleted by selecting 'edit' and then 'delete repository' from the bottom of the edit page.
+
On GitHub itself, you can inform keepers of the main branch of your changes by sending a 'pull request' from the main page of your branch. Once the file has been committed to the main branch, you may want to delete your now redundant bug fix branch on GitHub.  Branches can be deleted by selecting 'edit' and then 'delete repository' from the bottom of the edit page.
  
 
= Additional Resources =
 
= Additional Resources =
  
There is a lot of different nice guides to using git on the web:
+
There is a lot of different nice guides to using Git on the web:
 
* http://github.com/guides/git-cheat-sheet
 
* http://github.com/guides/git-cheat-sheet
 
* http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html
 
* http://zrusin.blogspot.com/2007/09/git-cheat-sheet.html
 
* http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/cvs-migration.html
 
* http://www.kernel.org/pub/software/scm/git/docs/v1.4.4.4/cvs-migration.html

Revision as of 05:46, 20 March 2009

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

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

This is 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. All developers and potential contributors are encouraged to try out this repository. Instructions on developing Biopython with Git follow below.

Contents

Prerequisites

Installing Git

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

Git (http://git-scm.com/) is now available for all major operating systems.

Linux

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

Ubuntu/Debian

You can install Git from the git-core package. e.g., sudo apt-get install git-core

You'll probably also want to install the following packages: gitk git-gui git-doc

Mac OS X

Download the .dmg disk image from http://code.google.com/p/git-osx-installer/

Windows

Two options exist for Windows: msysGit and running Git under Cygwin.

msysGit (Recommended)

msysGit is a port of Git that runs natively on Windows via the MinGW library. Because Git was not originally designed to run on Windows, and since this is a port, some bugs exist, though are rarely encountered in everyday use of Git. See their website for download and installation instructions. Additionally, you can watch Scott Chacon's screencast on installing msysGit on Windows, and see this GitHub guide.

Cygwin

Cygwin provides a Linux-like environment for Windows. It includes access to repositories of many software packages available commonly in Linux distributions, including Git. You can find the git package under the "devel" category.

Getting a GitHub account (Optional)

Once you have Git installed on your machine, you can get the code and start developing, 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:

  • create one here http://github.com/plans (the free plan is absolutely enough)
  • Upload an ssh public key by clicking on 'account' after having logged in

Obtaining the source code

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.

Forking without a GitHub account

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

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

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.

You may want to also link your branch with the official distribution:

git remote add official_dist git://github.com/biopython/biopython.git

You can find more info here: http://github.com/guides/keeping-a-git-fork-in-sync-with-the-forked-repo

To add additional contributors to your branch on GitHub, select 'edit' and then add them to the 'Repository Collaborators' section. You will need to know their username on GitHub.

Making changes

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 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.

On GitHub itself, you can inform keepers of the main branch of your changes by sending a 'pull request' from the main page of your branch. Once the file has been committed to the main branch, you may want to delete your now redundant bug fix branch on GitHub. Branches can be deleted by selecting 'edit' and then 'delete repository' from the bottom of the edit page.

Additional Resources

There is a lot of different nice guides to using Git on the web:

Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox