Developer Documentation

De Trustedbird Client Wiki
Révision de 9 novembre 2010 à 17:29 par Rfairise (discussion | contributions) (Upgrading Thunderbird)

Versioning convention

This chapter describes best practices for managing versions of universal messaging client Trustedbird and add-ons developed.

Version identifies the state of a program in its development. It is often associated with a numbering system which allows identification, and in some cases a symbolic name. The symbolic names are not used in this project.


Life cycle of a software





Life cycle of a software

phase alpha:

  • Available for an overview of the progress of the product, testing the functions currently implemented

phase beta:

  • The set of features is usually fixed, it is a test version to reach a maximum of bugs

release candidate:

  • Release candidate to be the final version

GA version (for General Availability):

  • Final version of the product. The version includes bug fixes found after the final version of the product, an upgrade may also be a new version of the product


Versioning usage

The version number will be as follows:

major.minor.revision.build

Note: the number associated with the revision, can be called maintenance.
Here is how to increment the values of the version number.

Values

Why to increment

When

major

  • Adding an important feature.
  • Significant change of behavior of the application.
  • Significant change in the appearance of the application.

As soon as developments start.

minor

  • Adding non-critical features in the application.
  • Evolution of features without change of the existing one.

As soon as developments start.

revision

  • Each delivery of bug patch (Even if there's only one correction).

Depends on the delivery of the final version:

  • BEFORE : 0 With a tag indicating what life cycle you are (alpha, beta or rc).
  • AFTER : Each time corrections are delivered.

build

  • Delivery internal or external distribution of a product.

Each time the distribution is published. For the service integration, service quality or final customer.


Git repository

Trustedbird sources are hosted on a Git repository.


The repository has 2 branches: "master" and "thunderbird".

  • "master" branch holds Trustedbird email client patch and add-ons.
  • "thunderbird" branch holds all the files from official Thunderbird sources which have been modified in "master" branch. This branch is used for upgrading Thunderbird when a new upstream release is available.


Build Documentation

Dependencies

Linux (Debian)

  • build-essential
  • ant
  • git-core
  • libgtk2.0-dev
  • libglib1.2-dev
  • libidl-dev
  • libxt-dev
  • zip
  • unzip
  • flex
  • bison
  • fakeroot
  • dpkg-dev
  • python-dev
  • autoconf
  • libtool
  • a Java JDK for Ant (java-gcj-compat-dev, sun-java6-jdk, openjdk-6-jdk,...) or JRE

Windows

  • For Thunderbird 2:
    • Microsoft Visual C++ 6 with Service Pack 5 (not Service Pack 6 because Processor Pack needs SP5)
    • Visual C++ 6.0 Processor Pack
  • For Thunderbird 3.1:
    • Microsoft Visual C++ 9 (Visual Studio 2008 Pro SP1 - Not the "Express" edition in order to build with jemalloc)
    • Windows 7 SDK
  • Latest MozillaBuild
  • Git
  • Java JRE (for Ant)
  • Ant


See http://developer.mozilla.org/en/docs/Windows_Build_Prerequisites for more info.


  • Add Ant path to the PATH variable in c:\mozilla-build\start-msvc9.bat:
SET PATH=%PATH%;%MOZ_TOOLS%\bin;C:\mozilla-build\apache-ant-1.8.1-bin\bin
  • Launch build environment with c:\mozilla-build\start-msvc9.bat

Cloning the repository

Read only (with HTTP/HTTPS)

~$ git clone http://adullact.net/anonscm/git/milimail/trustedbird.git


Read-write (with SSH)

~$ git clone ssh://USERNAME@scm.adullact.net/scmrepos/git/milimail/trustedbird.git
  (replace USERNAME with your Adullact SSH username)


Building

~$ cd trustedbird/packager
~/trustedbird/packager$ cd trustedbird/packager


Download Thunderbird source file:

~/trustedbird/packager$ wget ftp://ftp.mozilla.org/pub/thunderbird/releases/3.1.6/source/thunderbird-3.1.6.source.tar.bz2


Build and package Trustedbird email client:

~/trustedbird/packager$ ant -Dversion=3.1 trustedbird


⇒ All packages will be available in trustedbird/packager/dist/


[optional] In order to build and package the add-ons developed for the project:

~/trustedbird/packager$ ant package-addons

Upgrading Thunderbird

When a new upstream release of Thunderbird is available, we need to merge the changes into Trustedbird.

In order to do so, a special Git branch ("thunderbird") is available. It contains all files from official Thunderbird sources which have been modified in "master" branch for Trustedbird.

Note: current branch will be printed inside parentheses in the following examples.


In order to do the merge of a new Thunderbird release, we'll need to have this "thunderbird" branch in our local Git repository.


Extract new Thunderbird release into a directory (extracted files will be in ~/temp/comm-1.9.2):

~$ mkdir ~/temp
~$ tar xvfj thunderbird-3.1.6.source.tar.bz2 -C ~/temp/


Create a "thunderbird" local branch (if it doesn't already exist) which tracks the remote branch named "thunderbird":

~$ cd trustedbird
~/trustedbird (master)$ git branch thunderbird origin/thunderbird
~/trustedbird (master)$ git branch -a
* master
 thunderbird
 remotes/origin/HEAD -> origin/master
 remotes/origin/master
 remotes/origin/thunderbird

~/trustedbird (master)$


Switch to "thunderbird" branch:

~/trustedbird (master)$ git checkout thunderbird
~/trustedbird (thunderbird)$
~/trustedbird (thunderbird)$ cd trustedbird-patch-source-3.1/
~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$


Update files with new versions:

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ find -type f -exec cp ~/temp/comm-1.9.2/{} {} \;


Commit changes (if any):

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ git commit -va


Switch back to "master" branch:

~/trustedbird/trustedbird-patch-source-3.1 (thunderbird)$ git checkout master
~/trustedbird/trustedbird-patch-source-3.1 (master)$


Merge "thunderbird" branch into "master" branch:

~/trustedbird/trustedbird-patch-source-3.1 (master)$ git merge thunderbird


Resolve conflicts (if any) and commit:

~/trustedbird/trustedbird-patch-source-3.1 (master)$ git commit -va

How to build a localized Thunderbird 2

See Build Localized Thunderbird.

SSL certificates generation

In order to sign and encrypt messages, you'll need to have certificates.

Certificates can be generated with a Perl script CA.pl supplied with openssl.

  • 1) Create a certificate hierarchy in new directory demoCA/
$ /usr/lib/ssl/misc/CA.pl -newca

(type enter when prompted to create a new certificate and fill at least "Common Name" field)

=> demoCA/cacert.pem: root certificate (CA)
  • 2) Create a new certificate request for a user
$ /usr/lib/ssl/misc/CA.pl -newreq
=> newkey.pem: user's private key
=> newreq.pem: certificate request for the user
  • 3) Sign the certificate request with certificate authority key
$ /usr/lib/ssl/misc/CA.pl -signreq
=> newcert.pem: user's signed certificate
  • 4) Convert certificate to DER format (for LDAP)
$ openssl x509 -outform DER -in newcert.pem -out newcert.der
=> newcert.der: user's signed certificate in DER format
  • 5) Create PKCS#12
$ /usr/lib/ssl/misc/CA.pl -pkcs12 "Name of the certificate"
=> newcert.p12: root certificate, user's signed certificate and user's private key
  • 6) Revoke a certificate
 $ openssl ca -revoke newcert.pem
 $ openssl ca -gencrl -out crl.pem
 $ openssl crl -inform PEM -outform DER -in crl.pem -out crl.der
=> crl.pem/crl.der: certificate revocation list


Import a user's certificate into Thunderbird

Import newcert.p12 in "Your certificates" tab in Thunderbird certificate manager.

In "Authorities" tab in Thunderbird certificate manager, choose to trust the CA of the certificate to identify email users.

(do again step #2 to #5 to create a new certificate for another user issued by the same authority)

Manipulate DER/ASN1

Decode Base64 -> DER-encoded:

$ openssl base64 -d -in message.b64 -out message.der

View DER-encoded in human-readable text:

$ dumpasn1 message.der
OR
$ openssl asn1parse -in message.der -inform DER -i -dump

Decrypt DER-encoded with private key:

$ openssl smime -decrypt -in message.der -inform DER -inkey private.key.pem -out message.clear