commit e4469eac78603fb80c9cc81793588e8b2f6d4492 Author: Erinn Clark <erinn@torproject.org> Date: Tue Mar 29 03:09:45 2011 +0200 add preliminary hacking doc, with preliminary versioning and git branching information --- docs/HACKING | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 123 insertions(+), 0 deletions(-) diff --git a/docs/HACKING b/docs/HACKING new file mode 100644 index 0000000..e27206d --- /dev/null +++ b/docs/HACKING @@ -0,0 +1,123 @@ +How to Contribute to the Tor Browser Bundle +=========================================== + +General system layout +--------------------- + +The Tor Browser Bundle (henceforth known as 'TBB') consists of several +components of software: + +Main Players +- Tor +- Vidalia (front-end to Tor) +- Firefox + * Firefox extensions + - Torbutton + - HTTPS-Everywhere + - (Linux and OS X) NoScript + - (Linux and OS X) BetterPrivacy +Supporting Cast (libraries) +- OpenSSL +- zlib +- libevent +- Qt + +It works by having a launch script which opens Vidalia, which then launches +Firefox, pre-configured with Torbutton and other privacy-enhancing extensions. + + +Git branching strategy +---------------------- + +TBB's git strategy is based loosely on Tor's method. At any given time there +are three TBB branches which correspond to Tor's branches. Currently that +means: + +torbrowser.git + - master + - maint-2.3 + - maint-2.2 + - archive-1.0 + +master: +The master branch's versions are considered equivalent in spirit to Tor's +master branch, which is to say things under heavy and occasionally turbulent +development. This branch will use Tor's 'master' as its main Tor build, and all +other components in TBB will be equally alpha, which is to say, they ought to +be the kinds of things that are pulled directly from version control with +absolutely no guarantee that they will work separately or together. + +maint-2.3: +The maint-2.3 branch's versions correspond to Tor's 0.2.3.x series of releases. +Since 0.2.3.x is the next alpha release of Tor, all of the components of TBB +will mimic its stability, as above. This means it will be a testing ground for +newly released pieces of software, rather than relying on the latest commits in +the various components' version control systems. (As of current writing +(2011-03-29), 0.2.3.x is still the alpha-dev version of Tor, but it is expected +to become the normal alpha release soon.) + +maint-2.2: +The maint-2.2 branch's versions correspond to Tor's 0.2.2.x series of releases. +This is the (almost) incumbent stable branch of Tor, and of TBB. Every +component in this branch should consistently work together, and new versions of +non-Tor software can only be moved in once they have proven to be stable in the +maint-2.3 branch. New features and build improvements may be added to this +branch, but only after they have had sufficient testing in the alpha branch. + +archive-1.0: +This will be a record of all changes prior to the new git methodology. + +Versioning +----------------------- + +A brief history lesson is necessary to explain the versioning of TBB. + +The first version of TBB (0.0.1) was released 2007-12-11. It was Windows only +until 2010-03-25, at which point it was joined by the Linux version (1.0.0, +thusly versioned because Andrew said "Just call it 1.0.0. Users won't use +anything else.") At this point, Windows was at version 1.3.3. The OS X version +joined the fray on 2010-09-15 as version 1.0.0, at which point the Windows +version was at 1.3.9 and the Linux version was at 1.0.10. The Linux and OS X +versions were widely diverged from the Windows version in the sense that they +were alpha -- both in terms of overall bundle testing, and because they were +using the Tor alpha version. + +When your humble narrator took over all three of them, and the Tor 0.2.2.x +branch began to stabilize, it was clear that soon all three versions would be +able to use the same versions of software, and in order to remain consistent, +the version should meet the following requirements: + +1. It must be an increment of the previous shared version so as to avoid + confusing users +2. It must be consistent across operating systems +3. It must communicate the Tor version it contains +4. It must allow for package versioning that does not impact the Tor version +5. It should not make the filenames any longer +6. It should be flexible enough to allow for deviation between architectural + packages on the same operating system, or packaging changes irrespective of + operating system, while maintaining clarity about which 'family' the package + belongs to + +(For more information on the Tor versioning scheme, please see: +https://gitweb.torproject.org/torspec.git/blob/HEAD:/version-spec.txt) + +Based on the blend of TBB's old versioning system and Tor's current versioning +system, we end up with: +Tor's MINOR.MICRO.PATCHLEVEL(-status_tag)-tbb_ver(-tbb_status_tag)(-arch) + +If Tor is ever perfect and releases a major version that is non-zero we will +have to rethink this strategy. + +Tor's MINOR, MICRO, PATCHLEVEL, and status_tag are covered in its version spec. + +Official TBB releases must have 'tbb_ver' which refers to the current version +of the package, beginning with 1. + +Official TBB releases may have 'tbb_status_tag' if there is a good enough +reason. What constitutes a 'good enough reason' is left to the discretion of +the official maintainer and must have a corresponding git branch in the +maintainer's personal repo. Unofficial TBB releases must have 'tbb_status_tag' +as well as a corresponding git branch. + +Official TBB releases for more than one architecture must use 'arch' in the +filename.