Working with Torrus sources
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 firstname.lastname@example.org: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 "email@example.com"
Setting up the development directory and doing actual development:
cd ~/build/torrus/ git clone -b jsonrpc firstname.lastname@example.org: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 email@example.com:ssinyagin/torrus-newfeatures.git master # # verify and test everything, then push to SF.net Git repository git push