dolibarr_ynh/sources/dolibarr/build/debian

README (English)
##################################################
DEB Package tools
##################################################

This directory contains files used by makepack-dolibarr.pl
script to build a package, ready to be distributed,
with format .DEB (for Debian, Ubuntu, ...).



##### Prepare linux env to work

# To build a debian package, you need first
# With Ubuntu 12.04
# apt-get install debhelper dpkg-source gpg lintian git-buildpackage pkg-php-tools schroot sbuild dh-linktree dh-make-php
# With Debian 7
# apt-get install debhelper dpkg gnupg lintian git-buildpackage pkg-php-tools schroot sbuild dh-linktree dh-make-php


# To generate gpg key for email used into changelog
* Check your existing keys/emails
> gpg --list-key
* Generate a new one, if none exists for email you use as author
> gpg --gen-key							Generate a GPG key (-> pubring.gpg + secring.gpg)
Files are saved int .gnupg directory
* Create a file ~/.gpb.conf by
> cat >~/.gbp.conf <<END
[DEFAULT]
pristine-tar = True

[git-buildpackage]
sign-tags = True
export-dir = ../build-area/

[git-import-orig]
filter-pristine-tar = True
END


# Complete .bashrc with DEBEMAIL and DEBFULLNAME
Example:
export DEBFULLNAME="Laurent Destailleur (eldy)" 
export DEBEMAIL=eldy@users.sourceforge.net
Other example:
export DEBFULLNAME="Laurent Destailleur" 
export DEBEMAIL="eldy@destailleur.fr"


# To use Alioth.debian.org
* Create an account login
* Update your ~/.ssh/config file to add:
Host svn.debian.org git.debian.org bzr.debian.org hg.debian.org darcs.debian.org arch.debian.org
	User eldy-guest
	IdentityFile ~/.ssh/id_rsa
* Check login on page https://alioth.debian.org/users/login
Ex: https://alioth.debian.org/users/eldy-guest
* Setup your ssh as described into page: http://wiki.debian.org/Alioth/SSH
* Ask to be included into project collab-maint: http://alioth.debian.org/projects/collab-maint/



##### Some interesting command to know

# To translate .po files
# debconf-updatepo					     		To run into po dir to regenate templates.pot
# podebconf-report-po --from email@email.com	To send email to ask translations
# Edit manually file XX.po and remove all lines "#, fuzzy" when translation is complete
# msgfmt -v -c -o /dev/null XX.po		 		To have status of translation for language XX
 
# To check package integrity
# lintian --pedantic -E -I package.deb   To test a package   

# To manipulate packages
# dpkg -l                                List all packages
# dpkg -b                                To build binary only package
# dpkg -c package.deb                    List content of package
# dpkg -I package.deb                    Give informations on package
# dpkg -i package.deb                    Install a package
# dpkg-reconfigure -plow package		 Reconfigure package
# dpkg -L packagename                    List content of installed package 
# dpkg -r packagename                    Remove config files and interactive saved answers
# dpkg -s packagename                    Give status of installed package
# dpkg --purge                           Remove config files and interactive saved answers
#
# dpkg-buildpackage -us -uc              Build a source and binary package
#
# gdebi package.deb						 Install a package + dependencies



##### Global view of submit new package to Debian:

- Post an ITP with reportbugs :
> reportbug -B debian --email username@domain.tld wnpp
See page http://www.debian.org/devel/wnpp/#l1 for example of ITP requests contents.

- Wait until you received bug number.
  For first ITP submission of Dolibarr, bug id was 634783.

- Check bug is into database by searching with id on 
  http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=634783
  
- Add a line for upstream into file changelog with bug number

- Call for a mentor on ML debian-mentors to upload packages

- Once package is uploaded, following URL are available:
http://packages.qa.debian.org/package.html
http://bugs.debian.org/package


##### Modify severity of a bug ticket

- Send this email to control@bugs.debian.org and wait 10 minutes

severity 123 xxx


##### Update bug tracker system

To set status of a bug to "pending"
> bts --smtp-host=yoursmtpserver tag 999999 +pending

or replay to email 999999@bugs.debian.org + submitter of bug
With a message starting with: 

Control: tag -1 +pending
Thanks. Fixed into git.

or replay to email control@bugs.debian.org
With only message 
tag 729538 +pending



##### Testing a package into unstable env

Check you have a mysql server available from another interface than "localhost".
Comment line in /etc/mysql/my.cnf if required and restart mysql
#bind-address = 127.0.0.1

Create a chroot called "unstable-amd64-sbuild".
Chroot env is stored into /srv/chroot directory.
> sudo sbuild-createchroot --keyring= unstable /srv/chroot/unstable http://ftp.uk.debian.org/debian

Pour lister les env chroot
> schroot -l

Puis pour se connecter et préparer l'environnement 
> schroot -c name_of_chroot
> cat /etc/debian_chroot       to check which debian branch we are into
> vi /usr/sbin/policy-rc.d     and replace return code 101 (not allowed) into 0 (ok)
> apt-get install links mysql-client

Pour tester un package
> On host server, stop any server on port 80 and 3306 (same port will be used by chroot env)
> cp ../build-area/* /srv/chroot/unstable/tmp
> sudo schroot -c name_of_chroot
> cd /tmp
> lintian --pedantic -E -I dolibarr*.deb
> lintian --pedantic -E -I dolibarr*.dsc
> dpkg -i dolibarr*.deb  ou   pour avoir des traces: dpkg -D77777 -i dolibarr*.deb
> apt-get install -f

If there is a problem launching apache, because port is already used, change it into your chroot install with
> vi /etc/apache2/ports.conf
Then restart.
Then you can call/test dolibarr with http://localhost:port/dolibarr/ (It can be also called from host).




##### Create/Maintain TCPDF package

To update tcpdf package:

* You can git clone tcpdf
> git clone git.debian.org:/git/collab-maint/tcpdf.git [tcpdf-debian]
or better
> mkdir gitdebian
> cd gitdebian
> gbp-clone git.debian.org:/git/collab-maint/tcpdf.git

* You can then create a PHP project from Eclipse called tcpdf-debian
from git clone dir and make link to git.
 
* If local branch upstream and pristine-tar does not exists, create it
from origin/upstream and origin/pristine.

* Into root dir, launch:
> debian/get-orig-source.sh
If script fails with error Bad certificate, you can set "export PERL_LWP_SSL_VERIFY_HOSTNAME=0" to solve this.

* Some files are removed from archive by the get-orig-source.sh 

* Staying into git root directory, run
> git-import-orig -vv ../tcpdf_x.y.z+dfsg.orig.tar.xz --debian-branch=[master|jessie] --upstream-branch=[upstream|upstream-3.5.x]

Note: If there was errors solved manually, you may need to make a git commit

* Add an entry into debian/changelog
> dch -v x.y.z+dfsg-1 "My comment" will add entry.
For example: dch -v x.y.z+dfsg-1 "New upstream release." for a new version
Then modify changelog to replace "version" or "unstable" with "UNRELEASED".

Warning: Date must have format reported by "date -R"
Warning: Name and email must match value into debian/control file (Entry added here is used by next step).

* We try to build package
> rm -fr ../build-area; 
> git-buildpackage -us -uc --git-debian-branch=[master|jessie] --git-upstream-branch=[upstream|upstream-3.5.x]

Note: To build an old version, do: git checkout oldtagname -b newbranchname; git-buildpackage -us -uc --git-debian-branch=newbranchname --git-upstream-branch=[upstream|upstream-3.5.x]
Note: You can use git-buildpackage -us -uc --git-ignore-new  if you want to test build with uncommited file
Note: You can use git-buildpackage -us -uc -d                if you want to test build when dependencies does not match 
Note: Package is built into directory ../build-area
Note: To compare 2 packages: debdiff package1.dsc package2.dsc


* If package .deb is ok:
Note: If there was errors managed manually, you may need to make a git commit but do not use option "amend" previous commit
> git push --all ou git push origin --all

* If ok, you can tag.
> Edit debian/changelog to replace "UNRELEASED" into "unstable", then push
> git-buildpackage --git-tag-only --git-retag --git-debian-branch=[master|jessie] --git-upstream-branch=[upstream|upstream-3.5.x]
> git push --tags

* Compilation is then done by a debian developer and sent
> sbuild ...
> dput ...

* Go into page. You should see new package into unstable.
http://packages.qa.debian.org/t/tcpdf.html

* Package will be into release when test will be moved as stable.


##### Create/Maintain dolibarr package

To update dolibarr debian package when upstream version has changed

* You can git clone debian git repo
> git clone git.debian.org:/git/collab-maint/dolibarr.git [dolibarr-debian]
or better
> cd ~; mkdir git-debian; cd git-debian
> gbp-clone git.debian.org:/git/collab-maint/dolibarr.git

* You can then create a PHP project from Eclipse called dolibarr-debian
from git clone dir and make link to git.

* If local branch upstream and pristine-tar does not exists, create it
from origin/upstream and origin/pristine.

* When new upstream is available onto sourceforge, launch:
> debian/get-orig-source.sh
If script fails with error Bad certificate, you can set "export PERL_LWP_SSL_VERIFY_HOSTNAME=0" to solve this.

* Edit tgz file to remove 
- htdocs/includes/ckeditor
- htdocs/includes/jquery/plugins/datatables/extras/TableTools/swf
- htdocs/includes/phpexcel
- htdocs/includes/tcpdf
And rename file into 
dolibarr-x.y.z+dfsgw.tgz
(x.y.z = version, w start from 1 and is increased for each new git-import-orig already done)

* Staying into git root directory, run
> git-import-orig -vv ../dolibarr-x.y.z+dfsgw.tgz --debian-branch=[master|jessie] --upstream-branch=[upstream|upstream-3.5.x]
and enter version when requested with format
x.y.z+dfsgw
(x.y.z = version, w start from 1 and is increased for each new import)

Note: If there was errors solved manually after get-orig-sources.sh, you may need to make a git commit

* Fix debian/* files used to build package.
Add an entry into debian/changelog
> dch -v x.y.z+dfsgw-v "My comment" will add entry.
For example: dch -v x.y.z+dfsgw-1 "New upstream release." for a new version (x.y.z = version, w start from 1 and increased for each new import)
Then check/modify changelog to replace "version" or "unstable" with "UNRELEASED".
Then check/modify also the user/date signature:
- Date must have format reported by "date -R"
- Name and email must match value into debian/control file (Entry added here is used by next step).


To update dolibarr debian package when only files into debian has changed

* Change files and commit.
* Add a tag debian/x.y.z+dfsgw-2 (increase the last 1 into 2)


Once files has been prepared, it's time to test:

* Try to build package
> rm -fr ../build-area;
> git-buildpackage -us -uc --git-debian-branch=[master|jessie] --git-upstream-branch=[upstream|upstream-3.5.x]

Note: To build an old version, do: git checkout oldtagname -b newbranchname; git-buildpackage -us -uc --git-debian-branch=newbranchname --git-upstream-branch=[upstream|upstream-3.5.x]
Note: You can use git-buildpackage -us -uc --git-ignore-new  if you want to test build with uncommited file
Note: You can use git-buildpackage -us -uc -d                if you want to test build when dependencies does not match 
Note: Package is built into directory ../build-area
Note: To compare 2 packages: debdiff package1.dsc package2.dsc

* Test package (see dedicated chapter to test it with debian unstable env)

* If package .deb is ok:
Note: If there was errors managed manually, you may need to make a git commit but do not use option "amend" previous commit
> git push --all

* If ok, you can tag.
> Edit debian/changelog to replace "UNRELEASED" into "unstable", then push
> git-buildpackage --git-tag-only --git-retag --git-debian-branch=[master|jessie] --git-upstream-branch=[upstream|upstream-3.5.x]
> git push --tags


* Compilation is then done by a debian developer and sent
> sbuild ...
> dput ...

* Package arrives into FTPmaster taskboard with status NEW (pending upload). You can view it at:
http://ftp-master.debian.org/new/
 
* Once package is validated, you should see it into area unstable at:
http://packages.qa.debian.org

* Package will be into release when test will be moved as stable.


##### Send an unblock request 

Use this to move from unstable to testing.

reportbug -B debian
Choose package "release.debian.org"
Then "unblock"
Then name of package "dolibarr"
Fill message, for example:
"Please unblock package dolibarr
A security error CVE-2015-3935 was reported and is fixed into package 3.5.7.
Note that package 3.5.7 contains not only fixed for bugs reported to debian. It includes other fixes, but they are all related to stability or security,
so it is a better solution to validate this maintenance release than applying a patch of the only CVE-2015-3935. 
After discussion with ..., it appears that security holes are enough to request this unblock request."


Use this to request an update of a stable package

reportbug -B debian
Choose package "release.debian.org"
Then "unblock"
Then name of package "dolibarr"
Fill message, for example:
"Please unblock package dolibarr
A security error CVE-2015-3935 was reported and is fixed into package 3.5.7.
Note that package 3.5.7 contains not only fixed for bugs reported to debian. It includes other fixes, but they are all related to stability or security,
so it is a better solution to validate this maintenance release than applying a patch of the only CVE-2015-3935. 
After discussion with ..., it appears that security holes are enough to request this unblock request."