= Development Workflow for Trac

We don't have very formal rules, so consider the following as some advice taken from our current practices.

== Aim

The public branches (listed in TracDownload#LatestDevelopmentSourceCode) should ideally remain bug free and always usable from an end-user perspective, as we support people installing directly from there.


== Initial code review

Except for trivial fixes, it's usually a good idea to start with a patch or an experimental branch, in order to provide some visibility of the changes to the other contributors.

The patch is generally attached to a ticket.
When there are many iterations or spin-off changes, it's generally a good idea to start a branch, either in the svn [source:sandbox] for those who have the commit permission or inside an external DVCS repository, by forking our Mercurial or Git mirrors (see TracRepositories).


== Integration in release branches

The general idea is that we commit bug fixes first on one of the stable branch (e.g. [source:branches/0.12-stable]), then merge the fix to latter branches using svn's mergeinfo support.

Merging in this direction (//porting// or //forward porting//) makes it quite easy to merge all pending changes from one stable branch to the next, e.g. [source:branches/0.12-stable 0.12-stable] to [source:branches/0.13-stable 0.13-stable] (when we'll have it), then to [source:trunk]. This workflow is much simpler than the opposite one, //back porting//, which involves cherry-picking or careful "blocking" of changes which shouldn't be merged back. The SCM tools have generally better support for merging in this direction, even Subversion since version 1.5 ;-)

Here's a walk through example. We start by hacking on 
[source:branches/0.12-stable 0.12-stable]:
{{{
0.12-stable$ ed trac/attachment.py # or your other favorite editor ;-)
0.12-stable$ make test
...
(all is good)
0.12-stable$ svn ci -m "0.12.3dev: fixed ... (#xyz)"
}}}

Now we want to port all the pending changes to [source:trunk]:
{{{
0.12-stable$ cd ../trunk
trunk$ svn merge ^/branches/0.12-stable
trunk$ make test
...
xxx
trunk$ # some fixes needed for API changes
trunk$ svn ci -m "0.13dev: Merged from 0.12-stable."
}}}

Note: one can always review what are the pending changes in Trac by looking at the `svn:mergeinfo` property which shows the __eligible__ set of changesets, when viewing the target branch in the TracBrowser (e.g. [source:trunk])