[pkg-horde] tla primer slightly revised, Gregory's howto

[Lionel Elie Mamane]

On Mon, Jul 10, 2006 at 11:35:54AM +0200, Lionel Elie Mamane wrote:

> I'll try to add "why" explanations to my existing explanations.

I've looked at my "tla primer" and didn't find much to add in terms of
"why". I've added a bit, though. If anyone has any question, please
ask. Whole sections are missing, like "a new package", but
http://www.gcolpart.com/debian/horde/arch.php covers them. (I thought
I had covered them in another message, but I cannot find it.) Maybe
the latter would be better at http://pkg-horde.alioth.debian.org/howto
or something like that?

Errata about http://www.gcolpart.com/debian/horde/arch.php:

 Section "First commit of upstream sources", it says:

 echo "source ^\.htaccess$"  << \{arch\}/\=tagging-method

 it should be:

 echo "source ^\.htaccess$"  >> \{arch\}/\=tagging-method


Let's note that tla-load-dirs 1.0.29 contains support for "import"
instead of "commit", so that the procedure with tla_load_dirs for
"First commit of upstream sources" becomes:

 Create empty HORDE_APPLI--upstream--VERSION_NUMBER:

 $ tla archive-setup -A pkg-horde-hackers at lists.alioth.debian.org--2006 \
 HORDE_APPLI--upstream--VERSION_NUMBER

 Download your Horde webapp and:

 $ (tar xvf | (cvs co && rm CVS)) /path/HORDE_APPLI

 $ mkdir /path/HORDE_APPLI.tla.dir
 $ cd /path/HORDE_APPLI.tla.dir
 # this sets that empty directory as an empty tla tree for HORDE_APPLI--upstream--VERSION_NUMBER
 $ tla init-tree HORDE_APPLI--upstream--VERSION_NUMBER
 # tla tries to help you not commit compiled or other non-source files
 # (like .o for C sources) to the archive; it thus has a set of naming
 # rules to recognise them. By default filenames starting with "." are
 # forbidden to go to the archive, but horde apps use .htaccess
 # files. So change the naming rules to accept these as sources.
 $ echo "source ^\.htaccess$"  >> \{arch\}/\=tagging-method
 # the following requires version 1.0.29 or later.
 $ tla_load_dirs "-sImport from HORDE_APPLI VERSION_NUMBER"
 # BEGIN: with version before 1.0.29
 # tla_load_dirs -n "-sImport from HORDE_APPLI VERSION_NUMBER"
 $ YOUR-EDITOR `tla make-log`

 Enter text to comment your operation, for example "Import from HORDE_APPLI VERSION_NUMBER"

 $ tla import
 # END: with version before 1.0.29






TLA primer:

INTRODUCTION
============

You have to do the following one time only (on every machine you want
to use tla), replace YOUR NAME and YOUR.EMAIL at DOMAIN.TLD with ... your
name and email address.

 Install a recent version of tla and tla-load-dirs (in
 Debian). (Preferably tla tla-1.3.3-2 or newer and tla-load-dirs
 1.0.29 or newer.)

 # This registers your identity with tla. So the commits you make will
 # be marked as being made by "YOUR NAME <YOUR.EMAIL at DOMAIN.TLD>".
 tla my-id "YOUR NAME <YOUR.EMAIL at DOMAIN.TLD>"

 # This tells tla where the archive is located. It reads the name of
 # the archive, namely
 # "pkg-horde-hackers at lists.alioth.debian.org--2006" from the archive
 # itself.
 tla register-archive sftp://arch.debian.org/arch/pkg-horde/2006/
 # Tell tla this archive should be the default one. Alternatively, add
 # "-A pkg-horde-hackers at lists.alioth.debian.org--2006" to commands
 # that deal with an archive other than the current working tree.
 tla my-default-archive pkg-horde-hackers at lists.alioth.debian.org--2006

 # If you don't have a lightning fast Internet connection:
 # this will create a local cache of what you access
 # You can naturally choose another directory name.
 mdkir ~/arch-revlib/
 tla my-revision-library ~/arch-revlib/


A NEW DEBIAN REVISION
=====================

First, if you don't already have one, get a tla-ised copy of the "sid"
branch of the thing you are going to work on. E.g. if you are going to
work on nag2, do:

 # The first "nag--sid--2" is what you want to get, the second is
 # where you want to put it.
 tla get nag--sid--2 nag--sid--2

Then make your changes (replace $EDITOR with your favourite editor:
vim, emacs, ...):

 cd nag--sid--2
 # Here, make one change
 $EDITOR `tla make-log`
 # describe the change in the file that gets opened
 tla commit
 # Here, make one change
 $EDITOR `tla make-log`
 # describe the change in the file that gets opened
 tla commit
 # Here, make one change
 $EDITOR `tla make-log`
 # describe the change in the file that gets opened
 tla commit
 # Repeat as often as necessary


A NEW UPSTREAM RELEASE
======================

First, if you don't already have one, get a tla-ised copy of the
upstream _and_ sid branches of the thing you are going to work
on. E.g. if you are going to work on nag2, do:

 tla get nag--upstream--2 nag--upstream--2
 tla get nag--sid--2 nag--sid--2

unpack the new upstream revision somewhere, e.g.:

 tar xfz nag-h3-2.0.5.tar.gz
 #gets unpacked in nag-h3-2.0.5

and import it into our "upstream" branch

 cd nag--upstream--2
 # the tla_load_dirs command makes it so that the state of the
 # project--branch--version of the current working tree is exactly its
 # argument; it will do the necessary "tla add-id" and "tla rm", etc
 # automatically. If files have been added _and_ deleted,
 # tla_load_dirs cannot automatically determine whether these are
 # files that changed name (were moved) or whether they are deleted
 # files and new files. So it asks you. Try to answer the best you
 # can.
 tla_load_dirs -s'Import upstream nag 2.0.5' ../nag-h3-2.0.5

and then merge the changes into our sid branch:
 cd ../nag--sid--2
 # The following means "all changes made to nag--upstream--2 that were
 # not done here, do them"
 tla star-merge nag--upstream--2
 # Here, either everything goes well or you get conflicts. Conflicts
 # mean that Debian made changes and that upstream changed the same
 # lines of code in another way. If you have conflicts, you get files
 # named "foo.rej", which means a conflict occurred in file
 # "foo". These files contain the upstream changes that could not be
 # applied. Apply them by hand, or confirm that we don't want these
 # changes at all. Delete a .rej file after having handled it.
 #
 # "tla tree-lint" will list any .rej file that may be there.
 #
 # Once you have handled all .rej files (or there were none), commit
 # the changes:
 $EDITOR `tla make-log`
 # describe the change in the file that gets opened, something like:
 # Summary: Merge with upstream branch.
 tla commit
 # Edit debian/changelog and do any other work that needs to be done,
 # like in the section "A NEW DEBIAN REVISION"


BUILDING A PACKAGE FOR UPLOAD/TEST
==================================

First, if you don't already have one, get a tla-ised copy of the "sid"
branch of the thing you are going to work on. E.g. if you are going to
work on nag2, do:

 tla get nag--sid--2 nag--sid--2

Then, create a source package:

 cd nag--sid--2
 # The -i option is to exclude arch metadata from the package and -S
 # to make a source package only.
 debuild -S -i

and build that source package in the usual way (pbuilder if you use
pbuilder, ...). E.g.:

 cd ..
 pbuilder build nag2_2.0.5-18.dsc


-- 
Lionel