Debian VoIP Team
================

Contacts
--------
We have two different lists. The only "human" list is the maintainers list. 
The other has the only purpose of holding mails from SVN commits.

General discussion mailing list: <pkg-voip-maintainers@lists.alioth.debian.org>
SVN commits only mailing list (moderated): <pkg-voip-commits@lists.alioth.debian.org>

IRC: #debian-voip on irc.debian.org

Subversion repository
---------------------
You can browse it only at:

http://anonscm.debian.org/viewvc/pkg-voip/

You can find some commit statistics at:

http://cia.vc/stats/project/pkg-voip

To "checkout" the repository use these commands:

* If you want a read-only copy, use:

  svn co svn://anonscm.alioth.debian.org/svn/pkg-voip/

* If you are a developer with an account at Alioth, you can also use:

  svn co svn+ssh://${ALIOTH_USERNAME}@svn.debian.org/svn/pkg-voip/

Authorized SSH keys are controlled at https://alioth.debian.org/account/

The repository layout is:

* packagename/
    - trunk/
    - branches/
    - tags/

If only one version of the package is available at the time, development must 
be made at trunk/ dir, copying the dir to tags/'pkg-version' each time a new 
release is made.

When, at some point, the need to have two different versions at the same time 
arises (for example, if we need a version to be in unstable and a different one
to be in experimental), experimental development will be made in trunk/ and 
if a new unstable package needs to be cooked, copying tag/'latest_version_in_sid' 
to tag/'latest_version_in_sid'+1 will make the trick.

The according Vcs-Svn and Vcs-Browser stanzas in debian/control have the following 
syntax:

  Vcs-Svn: svn://anonscm.debian.org/pkg-voip/$PACKAGE/trunk/
  Vcs-Browser: http://anonscm.debian.org/viewvc/pkg-voip/$PACKAGE/

where of course $PACKAGE is the name of the SVN path (which should be identical
to the source name).

Homepage fields should be added to all pkg-voip packages to the Source part
unless really useful to have Source and Package point to different URLs.
The Homepage field is supported by dpkg-dev (>= 1.14.6).

If in doubt, sort the targets in debian/rules like this:
  1. headers, variable definitions
  2. includes (like dpatch, cdbs etc.)
  3. "build/build-arch/build-indep" targets including config.status and autotools/patch
  4. clean target (including unpatch)
  5. binary target
  6. get-orig-source and print-version target
  7. .PHONY definitions

To speed up the quite laggy ssh connection establishment process feel free to
update your ~/.ssh/config with the following:
Host svn.debian.org
  user yourusername
  ControlPath /tmp/ssh_svn.d.o_control

Once added run "ssh -fMN svn.debian.org" to establish the link and make it
background. From there on no more password will be required as the ssh
connection is held open by the ssh process. (You may find it helpful to add
this to your logon scripts)


Using svn-buildpackage
~~~~~~~~~~~~~~~~~~~~~~
Packages with an upstream tarball will require you to set the mergeWithUpstream
property first (from the package root) so that svn-buildpackage will look for
the .orig.tar.gz in the ../tarballs directory.
	
  % svn propset mergeWithUpstream 1 debian

Please note that this only works for packages which have only the debian/
directory committed. Consequently, you must modify upstream sources indirectly
using some patch system like CDBS's simple-patchsys.mk, CDBS + patchsys-quilt or
dpatch.

To download the *.orig.tar.gz to the ../tarballs directory, most of the
pkg-voip packages have a "get-orig-source" target in their debian/rules.
Further, there is a "print-version" target showing the upstream version used for
the current packaging. You can run the get-orig-source directly from trunk/ or
tags/$version/.

After you have finished and committed your Debian patches via
	
  % svn commit [PACKAGE]

as well as copying the orig.tar.gz to ../tarballs/ if necessary, you may build
your package with the following commands:

  % svn-buildpackage -rfakeroot

You might want to add --svn-ignore-new to the flags if you do not want to
commit before having finished your testbuild. Further, if you use debuild and
edited /etc/devscripts.conf to use fakeroot by default, there is no need to add
this to svn-buildpackage.

svn-buildpackage provides svn-do, which you may find useful:
  % /usr/share/svn-buildpackage/contrib/svn-do
It executes svn-buildpackage --svn-export and enters that directory. After
you change the tree as you like, exit the shell; your changes will be copied
back to your working tree.
Note, however, that it doesn't automatically "svn add" the new files that you
may have created (e.g. debian/patches/foo); you'll have to do this manually.
You may also want to edit the script and add --svn-ignore to the
svn-buildpackage options.

Don't commit tarballs/ or build-area/ directory contents to SVN! They would be
wasting loads of bandwith and there is no point.

What you may find useful is setting these two:
-------------------------------------------------
$ cat >> ~/.devscripts <<EOF
DEBCHANGE_RELEASE_HEURISTIC=changelog
DEBCHANGE_MULTIMAINT_MERGE=yes
DEBCHANGE_MAINTTRAILER=no
DEBUILD_ROOTCMD=fakeroot
DEBUILD_DPKG_BUILDPACKAGE_OPTS="-us -uc"
DEBUILD_LINTIAN=yes
DEBUILD_LINDA=yes
DEFAULT_DEBRELEASE_DEBS_DIR=../build-area/
EOF

cat >> ~/.svn-buildpackage.conf <<EOF
svn-builder=debuild
svn-noautodch 
EOF

-------------------------------------------------

to make using "dch" just do the RightThing(TM).

Common conventions for debian/changelog are:
* "New upstream release" goes on top without having the Changed-By name
  refering to it.
* "NOT YET RELEASED" doesn't need to be added no more since "svn-noautodch" and
  "DEBCHANGE_RELEASE_HEURISTIC=changelog"
* distribution needs to be UNRELEASED for all pending patches and one of
  unstable, proposed-updates, testing-proposed-updates etc. for uploaded
  packages. 
* Grouping of Changed-By is largely apprechiated. If there is only one editor,
  the preamble with the name should be removed if it was added accidentially.
  (use DEBCHANGE_MULTIMAINT_MERGE=yes will help a lot here)
* Try to be verbose about what the change is and prefer "debcommit" to not have
  different wordings for the same action. If SVN log and changelog match as
  close as possible, it's easier to spot a change.
* when releasing, use the text "Releasing $SOURCE ($VERSION) to $DIST." as SVN
  commit message to make finding these updates more easy (and eventually allow
  for a hold-back through IRC).

To have a broader understanding of what problems are already assigned, use the
"tagpending" whenever you think your fix is ready to solve the problem. For all
the other manipulation like bug fowarding etc. using the "bts" commandline tool
may come in handy.

Tarballs and Build-area directories
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You need to place those dirs in the parent directory of the one from which you're 
running svn-buildpackage. Usually this means placing tarballs/ and build-area/ dirs 
in 'pkgname'/ dir, at the same level as trunk/

For the existing projects these are preset as symlinks to a central hierarchy
under the pkg-voip SVN root. This is to faciliate the building of subsequent
packages when having the full tree checked out.

If you want to compile inside one version in tags/ dir, you'll need to place those
dirs inside that dir. Also for most of the tags dirs there should be ready to
use symlinks.

With DEFAULT_DEBRELEASE_DEBS_DIR pointing to ../build-area you can just use the
"debrelease" command from the trunk/ directory after running svn-buildpackage
--svn-tag.

Using svn-inject
~~~~~~~~~~~~~~~~
To inject a new package into the Debian VoIP SVN archive you should use svn-inject(1)
as follows:
	
	svn-inject -o <package>.dsc svn+ssh://${ALIOTH_USERNAME}@svn.debian.org/svn/pkg-voip/

Type in your alioth password a few hundred times :-) and your package should be 
uploaded to the archive.  Note you will also need to manually copy the 
package.orig.tar.gz to your tarballs directory.  The -o option is important as 
this ensures that we 'Only keep modified files under SVN control'


Git repositories
----------------
We have a set of git repositories on Alioth, all under `pkg-voip`. See
http://wiki.debian.org/Alioth/Git

* Browse a repository: http://anonscm.debian.org/gitweb/?p=pkg-voip/foo.git
* Read-only clone: `git clone git://anonscm.debian.org/pkg-voip/foo.git`
* As a developer: `git+ssh://git.debian.org/git/pkg-voip/foo.git'

Authorized SSH keys are controlled at https://alioth.debian.org/account/

Creating a Git Repository
~~~~~~~~~~~~~~~~~~~~~~~~~
Here is what you need to create the repository ''foo'':
------------------------
  ssh git.debian.org
  cd /srv/git.debian.org/git/pkg-voip

  # Create repo:
  mkdir foo.git
  cd foo.git
  git init --bare

  # Fix HTTP access:
  mv hooks/post-receive.sample hooks/post-receive

  # Notifications:
  echo /home/groups/pkg-voip/scripts/pkg-voip-post-receive >> hooks/post-receive
  git config --add hooks.mailinglist pkg-voip-commits@lists.alioth.debian.org
  echo $project_short_name >description
------------------------
Now push your content into the repository. Run the following from the
directory of your git repository:

--------------------------
  git remote add alioth git+ssh://git.debian.org/git/pkg-voip/foo.git
  git push alioth master
--------------------------


Patch management systems
------------------------
Since all of our packages use mergeWithUpstream (we only keep debian/ in the
repository) a patch management system should be used to make changes to
upstream files. Most of the packages use '3.0 (quilt)' format. Some still
use manual quilt or dpatch.

dpatch
~~~~~~
Using dpatch is as easy as putting
-------------------------------------------------
	include /usr/share/dpatch/dpatch.make
-------------------------------------------------
to your debian/rules. This creates three new targets, "patch" and "unpatch"
which are phony and patch-stamp that's not phony which can be used as depends
upon on configure and clean respectively. For clean you'll need to make sure
unpatch is run after the regular cleanup or rerun builds will fail in clean.

quilt
~~~~~
Similarly, using quilt is as easy as putting
-------------------------------------------------
	include /usr/share/quilt/quilt.make
-------------------------------------------------
to your debian/rules. This creates three new targets, "patch" and "unpatch"
which are phony and patch-stamp that's not phony which can be used as depends
upon on configure and clean respectively. For clean you'll need to make sure
unpatch is run after the regular cleanup or rerun builds will fail in clean.


It is recommended to use these settings so that you can move around on your
series with quilt:
-------------------------------------------------
cat >> ~/.quiltrc <<EOF
QUILT_PATCHES="debian/patches" 

QUILT_PATCH_OPTS="--unified-reject-files" 
QUILT_REFRESH_ARGS="-p ab --no-timestamps --no-index" 
QUILT_DIFF_OPTS="--show-c-function"
QUILT_DIFF_ARGS="-p ab --no-timestamps --no-index --color=auto"
EOF

-------------------------------------------------
Consult quilt(1) for more information of what these options do.

Versioning 
----------
As the autobuilder and fellow developers will need to differentiate between
versions that are uploaded into debian already and those which will be at a
later point, do use the UNRELEASED distribution until the time you actually do
upload to incoming. Whoever is not a DD himself should let the sponsor do that
final step if that sponsor has SVN commit rights to the pkg-voip archive.


Automatic Backport hooks
------------------------
The checkout script for putting together the sources can run a backports hook
for certain dists (like Debian sarge) which need certain adjustments to the
source like altered Build-Depends. This hook is a plain shell script (or
makefile like debian/rules) which needs to be put in the debian/backports
directory and made executable by means of the SVN properties set. The codenames
for the current dists are: sid, etch, sarge, edgy and dapper. For an example
see asterisk-addons/trunk/debian/backports/sarge which may be more illustrating
what to do.


Building from debcheckout
-------------------------
This section is for someone who does not normally build pkg-voip 
packages and wants to build the latest version of a certain package 
without all the extra setup mentioned above.

Required packages (beyond the build requirements of the package)
* svn-buildpackage (and subversion itself, of course)
* devscripts

Here is an example build of the package libpri:

  debcheckout libpri
  cd libpri
  ./debian/rules get-orig-source
  # optionally: run: debian/backports/<distro-name>
  # e.g: debian/backports/lenny
  svn-buildpackage -uc -us

If all worked well, svn-buildpackage will print out the locations of the
binary packages it has generated. They will be built in the directory
../build-area/ .

-(snip)-


This file
---------
This file is a asciidoc-formatted file that resides on the top-level
directory of the pkg-voip team's subversion repository. Testing them:

  asciidoc -n -a toc README

and check the generated README.html . Once you updated it and commited
the changes, run the following to apply them:

  ssh wagner.debian.org 'make -C /home/groups/pkg-voip/htdocs clean all'


In case any of the above is unclear to you or seems outdated, please drop us
a note to the maintainers list.

Your
Debian pkg-VoIP packaging team