Bug#743474: Please add a debian/README.source file

Thu Jan 26 17:12:35 UTC 2017

Hi,

It would be good if the next release (or the pkg- repository)
of Linphone gets a debian/README.source file.

Debian policy says
in https://www.debian.org/doc/debian-policy/ch-source.html#s-readmesource

| 4. Optionally, document what steps are necessary to upgrade the Debian
| source package to a new upstream version, if applicable.
| 
| This explanation should include specific commands and mention any
| additional required Debian packages. It should not assume familiarity
| with any specific Debian packaging system or patch management tools.

I think it will help getting new releasessss of Linphone in Debian.

Find attached the README.source that I wrote
for the Debian package 'urjtag'.
Have look at it for the idea of this request.

Groeten
Geert Stappers
-- 
Leven en laten leven
-------------- next part --------------

Hi,

You might be reading this after doing

  apt-get source urjtag

Which is fine.

For actual package maintenance you need to install some tools.

     sudo apt-get install build-essentials
     sudo apt-get install devscripts # for `debcheckout`
     sudo apt-get install git-buildpackage # for `git-pbuild`

Prepare a clean build environment for later.

     git-pbuilder create

Then get the version from "git"

Either
     debcheckout urjtag
or
     git clone $( awk '$1 ~ /Vcs-Git:/ { print $2 }' debian/control )

You (should) have now a directory "pkg-urjtag".

Branch convention from `git-buildpackage` is used:
 * 'master' contains "debian branch"
 * 'upstream' is "upstream"
and there is the branch 'inbetween'  (for now)

Upstream URL (2016-10-30) is
git://git.code.sf.net/p/urjtag/git
and there is a svn, subversion, repository.

The git repo is preferred above the svn repository,
but the version number is used from svn.
Example given r2054

= Workflow =

Be in directory 'pkg-urjtag'
or even better in directory 'pkg-urjtag/urjtag'.

Get upstream branch

    git remote add sourceforge git://git.code.sf.net/p/urjtag/git
    git fetch sourceforge
    git branch upstream sourceforge/master

At this point starts regular packaging maintenance.

Switch, if you are not allready there, to the urjtag directory.
A command like

   tail debian/README.soure

should work.

See what is new in upstream:

   git checkout upstream
   git pull

Find what the SVN revision number is, do
   git log | grep -e git-svn-id -e ^commit | head -n 6

Expect output like
 commit bac6b34d8e278df25b178ea929d2c41ba6a146e5
  git-svn-id: svn://svn.code.sf.net/p/urjtag/svn/trunk@2054 b68d4a1b-bc3d-0410-92ed-d4ac073336b7
 commit 7ba12da7845af7601e014a2a107670edc5d6997d
  git-svn-id: svn://svn.code.sf.net/p/urjtag/svn/trunk@2053 b68d4a1b-bc3d-0410-92ed-d4ac073336b7
 commit 1949effb7a0226e34703d4575afb999acefce9a6
  git-svn-id: svn://svn.code.sf.net/p/urjtag/svn/trunk@2052 b68d4a1b-bc3d-0410-92ed-d4ac073336b7
>From that output is it the "trunk at 2054"
that translates into 'r2054' as the SVN revison number.

Switch to the pkg-urjtag branch 'inbetween' and bring it in shape

   git branch inbetween origin/inbetween
   git checkout inbetween
   git rebase upstream

For your information you may check where pkg-urjtag branch inbetween
differs from upstream. Contact upstream to reduce it.

   git diff upstream

Create "orig tar xz"

   tools/generate_orig_tar_xz.temporary r2054
( It is work in progress that
   tools/generate_orig_tar_xz r2054
can be used.)

For convinience set the version in a shell environment variable.

   export TV="0.10+r2054"

TV is here short for This Version.

Git tag this "point" / "milestone".

   git tag upstream/${TV}

Switch to branch with the Debian packaging directory

   git checkout master

Integrate the upstream tarball. Note you are still in the urjtag
directory, the debian directory is one level lower.

   tar xf ../urjtag_${TV}.orig.tar.xz --strip-components=1
   # see what is updated
   git status
   git status --ignored
   cp po/*.po debian/po/
   git add po/*.po debian/po/*.po
   # git  add / rm   more/files
   git commit # -m "Added upstream version ${TV}"

Check if the debian patches still apply.

   export QUILT_PATCHES=debian/patches
   quilt push -a
   quilt pop -a

Bring your build environmant up to date.

   git-pbuilder update

Verify that it builds.

   git-pbuilder -uc -us 2>&1 | tee ../build.log

Check the build log file

   less ../build.log

Make a judgement what additional work needs to be done.

Lintian check

   lintian ../urjtag_${TV}-1.dsc
   lintian ../urjtag_${TV}-1_amd64.changes
   lintian  -I --show-overrides --pedantic -E ../urjtag_${TV}-1_amd64.changes

Make a judgement what additional work needs to be done.

Install, uninstall and install again. If I recall correct
could this test be done with a tool like "puiparts"

   sudo dpkg --install ../urjtag_${TV}-1_amd64.deb ../urjtag-common_${TV}-1_all.deb
   sudo dpkg --remove urjtag urjtag-common
   sudo dpkg --install ../urjtag_${TV}-1_amd64.deb ../urjtag-common_${TV}-1_all.deb

Test

   jtag    # because that is the name of the binary, not urjtag
   ## the actual tests
   # cable
   # scan
   quit

Make a judgement what additional work needs to be done.

Git tag

   git tag debian/${TV}

And push to an online repo

   git push
   git push --tags

If you have the privileges of being a Debian Developer or Debian Maintainer.
Sign and upload.

   # debrsign ...   ... ...changes
   # dput ... . changes

= Notes =

== About Quilt and patches ==

Upstream does git ignore *.patch, doing `git add debian/patches/*.patch`
will suggest doing `git add -f debian/patches/*.patch`
Do so, if you want to add a new patch.

== git-pbuilder ==

git-pbuilder works for building urjtag in a clean environment.
It might be missing using that tool for it.
Reason that it went into use, was because `git-buildpackage`
was previously used succesfull for another package.

== upstream, upstream/web and upstream/urjtag ==

Upstream has one repository with toplevel directores 'web' and 'urjtag'.
In november 2016 couldn't git-buildpackage cope with 'urjtag' directory
being a directory under the  upstream toplevel directory.

== licensecheck ==

FWIW the licensecheck stuff is something that is not obvious

== Commands ==

To filter out the commands in this document
  sed --silent '/^   /s/^   \(.*\)/\1/p' debian/README.source

About the leading spaces:
 5: initial setup and how to get this document
 4: defining "upstream"
 3: regular maintenance commands

# l l