dolibarr/build/debian/README.howto

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 Ubuntu 14.04 ou Debian 7
# apt-get install debhelper dpkg gnupg lintian git-buildpackage pkg-php-tools schroot sbuild dh-linktree dh-make-php packaging-dev


# 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

[buildpackage]
ignore-branch = 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"

export QUILT_PATCHES=debian/patches


# Note: alioth.debian.org is outdated --> https://alioth-archive.debian.org/  -->  https://salsa.debian.org/public 
 * 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 binary package   
# lintian --pedantic -E -I package.dsc   To test a source 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 https://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 
  https://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:
https://packages.qa.debian.org/package.html
https://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


To remove status of a bug without "moreinfo" (bug can be processed)

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

Control: tag -1 -moreinfo
Thanks. Fixed into git.

or replay to email control@bugs.debian.org
With only message 
tag 729538 -moreinfo



##### Testing a package into a chroot environment

Check you have a mysql server available from another interface than "localhost".
Set line in /etc/mysql/my.cnf if required and restart mysql

[mysqld]
bind-address           = *

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

Pour lister les env chroot
> schroot -l
or
> ls /srv/chroot

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

To test a 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 --no-tag-display-limit --pedantic -E -I dolibarr*.deb
> lintian --no-tag-display-limit --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 (port must be a not used port on 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 

* Modify the tag file to replace sRGB.icc with correct free version and rename file into
tcpdf_x.y.z+dfsgw.orig.tar.xz
(x.y.z = version, w start from 1 and is increased for each new import)

* Staying into git root directory, run
> git-import-orig -vv ../tcpdf_x.y.z+dfsgw.orig.tar.xz --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, you may need to make a git commit

* Add an entry into debian/changelog
> dch -v x.y.z+dfsgw-1 "My comment" will add entry.
For example: dch -v x.y.z+dfsgw-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-x.y.z]
ou
> git-buildpackage -us -uc --git-ignore-branch --git-upstream-branch=[upstream|upstream-x.y.z]

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
> cp ../build-area/* /srv/chroot/unstable/tmp
See rest of process into dedicated chapter "To test a package" 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 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 (official version of external project) 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 orig.tar.gz file to remove 
- debian
- htdocs/includes/ckeditor
- htdocs/includes/jquery/css
- htdocs/includes/jquery/js
- htdocs/includes/jquery/plugins/flot
- htdocs/includes/jquery/plugins/multiselect
- htdocs/includes/jquery/plugins/datatables
- htdocs/includes/jszip
- htdocs/includes/mike42
- htdocs/includes/phpoffice
- htdocs/includes/restler/framework/Luracast/Restler/explorer
- htdocs/includes/swiftmailer
- htdocs/includes/tcpdf or htdocs/includes/tecnickcom
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 projet gitted 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

* Update/fix debian/* files used to build package.
At least, add an entry into debian/changelog with command
> dch -v x.y.z+dfsgw-1 "My comment"
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 line into changelog for version debian/x.y.z+dfsgw-v (increase the last v into 2, 3...)
> dch -v x.y.z+dfsgw-v "My comment"
* git tag will be added when package is pushed.


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

* Checkout the branch you want to work on: master of debian/...  
* Manually, add patches into debian/patches and update the file debian/series, or do the 2 steps with "quilt import filepatch.patch"
* You can test patching of serie with "quilt push" (autant de fois que de patch). Avec "quilt pop -a", on revient a l'état du upstream sans les patch.
* Update the debian/changelog to add entry of change.

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-jessie|upstream-3.5.x|3.5.5]
ou
> git-buildpackage -us -uc --git-ignore-branch --git-upstream-branch=[upstream|upstream-jessie|upstream-3.5.x|3.5.5]

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-jessie|upstream-3.5.x|3.5.5]
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)
> sudo rm /srv/chroot/unstable/tmp/* >/dev/null 2>&1; cp ../build-area/* /srv/chroot/unstable/tmp
See rest of process into dedicated chapter "To test a package" 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 to make a full update of a stable package 

Use this to move from unstable to testing.

reportbug -B debian --smtphost=smtp.gmail.com:587 --smtpuser=xxxx --smtppasswd=yyyy --tls
Choose package "release.debian.org"
Then usertag "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 full update of a stable package

reportbug -B debian --smtphost=smtp.gmail.com:587 --smtpuser=xxxx --smtppasswd=yyyy --tls
Choose package "release.debian.org"
Then usertag "unblock"
Then name of package "dolibarr"
Fill message, for example:
"
A security error CVE-2015-3935 was reported for Dolibarr ERP CRM package. This bug is fixed into official package 3.5.7 of Dolibarr.
Package 3.5.7 is a maintenance release compared to 3.5.5 and contains only fixes. But not only bugs reported to debian, it includes also other fixes (but they are all related to stability or security).
I think it is a better solution to validate this maintenance release based on the new upstream version of Dolibarr than applying a patch of the only CVE-2015-3935.
Pro are:
- It fixes all debian reported bugs (including security one)
- It fixes also stability bugs
- Patches were already tested because deployed and used by several thousands of users.
- It is easier for package maintener to include this official set of fixes than applying one patch after one patch for each debian report or backported each patch into a dedicated version.
- Debian maintenance version is inline with official project maintenance version (better when all fixes are not related to the way the software is packaged)
Cons are: 
- The patch include more than the only one security reported fixes

So I just need to know if it's ok to push such a version 3.5.7 (fixes for 3.5.* branch) instead of only one fix for only the few (the only) reported debian bugs,
since it provides more stability and is for me a more secured process.
"

##### Send an request to ask a simple fix of a stable package 

Use this to ask to apply patches on a stable version.

reportbug -B debian --smtphost=smtp.gmail.com:587 --smtpuser=xxxx --smtppasswd=yyyy --tls
Choose package "release.debian.org"
Then usertag "jessie-pu" (if tags is not available in list, choose another one, and change it later into email content text)
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."

Note: If there is a response to ask more information, don't forget to remove the tag during answer.