Working with Torrus sources

From torrus

Contents 1 Introduction 2 Stable branch at SF.net 3 Current development: torrus-newfeatures @github 4 Developing your own feature 5 Developing your own feature: actually coding 6 Sending your contributions to Torrus maintainer

Introduction

Starting February 6th 2011, Torrus source revision control is switched from Subversion to Git. The old Subversion directory is still available for historic reasons, but will not be updated any longer.

Git brings a completely different way of working with source code. For those unfamiliar with it, it's recommended to read at least 1/3 of the Pro Git book. The book is available in paper form. Also its source text is freely available, and quite easy to convert to a ePub or PDF file for your e-book reader.

Stable branch at SF.net

The master branch at SF.net Git repository contains the latest stable version of Torrus and its plug-ins. This latest update from this branch is always published as Torrus development snapshot at torrus.org website.

Initialize your local copy of the master branch:

cd ~/build
git clone git://torrus.git.sourceforge.net/gitroot/torrus/torrus torrus.sf.master
cd torrus.sf.master/src/
autoreconf

At this point your copy of Torrus sources is ready for deployment via the normal sequence:

./configure [options]
make && make install

Update your copy with latest updates from the master branch:

cd ~/build/torrus.sf.master
git pull

You can subscribe to the RSS feed at SF.net to be informed about all recent updates in the master branch.

Current development: torrus-newfeatures @github

The torrus-newfeatures project at Github is where all the current development is going on.

The master branch is the most stable version of the current development, and its contents are pushed to sourceforge.net master branch.

Other few branches contain newly developed features, and from time to time they are merged into the master branch.

Here's how I initialized the the Github repository:

cd ~/build/
mkdir torrus-newfeatures
cd torrus-newfeatures
git init
#
# add the URLs to our two repositories
git remote add origin git@github.com:ssinyagin/torrus-newfeatures.git
git remote add sourceforge git://torrus.git.sourceforge.net/gitroot/torrus/torrus
#
# retrieve the upstream code 
git pull sourceforge master
#
# upload to Github
git push --all origin
#
# set the current branch to "master"
git checkout master
#

Here's how I update the master branch with latest changes from SF.net:

cd ~/build/torrus/torrus-newfeatures
#
# pull latest changes from sourceforge into master branch
git pull sourceforge
#
# update the master branch on Github
git push

Here's the reverse operation: I push the latest changes from torrus-newfeatures onto SF.net:

cd ~/build/torrus/torrus.sf.master/
#
# pull latest changes from torrus-newfeatures into master branch
git pull ../torrus-newfeatures/ master
#
# update the master branch on SF.net
git push

Developing your own feature

In addition to standard Git features, Github provides some nice features for collaborative development.

In a standard, Git "classical" way, you would clone of the Torrus repositories, then create your own branch, commit to it, and then point the Torrus author to your repository for new patches.

With Github, you would usually "fork" the original repository into your own Github account. Then Github tracks all the differences between your repo and the original one, and provide you with the possibility to issue a "pull request" to the original repository's owner. This way, there is much more fun in collaboration and inter-developer communication.

Some coding and contributing guidelines follow:

• Your contributions are very much appreciated, unless they add headache :)
• Do not use any massive automatic formatting tools like Perltidy. They mess up with the code dramatically, so that merging becomes too uneasy.
• Group your changes logically into fewer commits. Ideally a new feature should occupy exactly one commit.
• Add meaningful messages to your commits. A commit named "update" will be rejected immediately.
• In general, Torrus patching policy is quite conservative, and every change should be driven by a purpose. The primary goal is to keep the software backward compatible, and to generate as less as possible effort for those who maintain their own set of patches.
• Do not send styling or re-styling patches, like removing extra spaces, replacing some old-school Perl constructs, and so on. Feel free to suggest a change, and I will think if the change is worth the benefit.
• Trailing spaces are OK. Yes, some editors markup them with a screaming colour, so you'd need to disable that. I even wrote a script that cleans up the spaces, but never have run it since many years (src/setup_tools/normalize-all-sources.pl). It's just too destructive, and breaks all the history of changes.

Developing your own feature: actually coding

Setting your Git globals for the first time:

git config --global user.name "Tekkub"
git config --global user.email "tekkub@gmail.com"

Setting up the development directory and doing actual development:

cd ~/build/torrus/
git clone -b jsonrpc git@github.com:ssinyagin/torrus-newfeatures.git torrus.jsonrpc
cd torrus.jsonrpc
git remote add sourceforge git://torrus.git.sourceforge.net/gitroot/torrus/torrus
#
# here we're ready to do something
cd src
autoreconf
#
## do the development, test, commit, and upload the changes
git add perllib/Torrus/Renderer/JsonRPC.pm
git commit -m 'New JSON-RPC method: "order-pizza"'
git push

Updating the development directory with the changes from other branches:

cd ~/build/torrus.jsonrpc
#
# retrieve latest changes from SF.net
git pull sourceforge master
#
# retrieve latest changes from master branch on Gitgub
git pull origin master
#
# if needed, push the merged branch back to Github
git push

The maintainer of the master branch on Github would to this to update it with the changes from jsonrpc:

cd ~/build/torrus-newfeatures/
git fetch origin jsonrpc
git merge FETCH_HEAD
#
# alternatively, the following command would work instead of fetch+merge:
git pull origin jsonrpc

Sending your contributions to Torrus maintainer

You are a maintainer of your own development branch, and you would like your contribution to be merged into the master branch at SF.net. You simply need to send a merge request to the maintainer. The best way is to send it to torrus-devel mailing list. You can also contact the author directly.

The best way of doing the merge is when your development branch is already updated with the latest changes from SF.net master branch.

Specify the following things in your merge request:

• read-only URL to your Git repository
• branch name (usually "master")
• if available, a URL to some Web-based browser of your repository, like that at Github.

In this example, as a maintainer of Torrus package on SF.net, I pull the changes from "torrus-newfeatures" project at Gitgub:

cd ~/build/torrus.sf.master/
git pull git@github.com:ssinyagin/torrus-newfeatures.git master
#
# verify and test everything, then push to SF.net Git repository
git push