This file outlines the general steps the author took in updating
debram (0.6.4) to (0.6.5), including several specifics where
appropriate.  These steps are not really scriptable (if they were, the
author would have scripted them) and they probably require some judgment
and understanding to follow profitably.  However, seeing how the author
went from (0.6.4) to (0.6.5) may at least save you some needless
confusion, if you find yourself maintaining the package for the first
time.  The steps are good.  Follow them generally, and you can release a
well trimmed debram update.  (This file is admittedly not as polished as
one would like.  The author doubts that many people will read it, so it
does not seem worthwhile for the author to spend an excessive amount of
time on it.)

The steps refer to versions "0.6.4" (old) and "0.6.5" (new), but these
numbers are just for illustration.  The author has already done the
actual update from (0.6.4) to (0.6.5).  Hence, where "0.6.4" and "0.6.5"
appear, you should substitute the old and new version numbers which
apply to your present debram update work.

1.  Ensure that you have the correct Packages and Sources files for the
distribution you are working on.  There are more than one way to get or
construct these files.  For example, you can download them from a
convenient Debian FTP mirror, or concatenate them from an official set
of Debian CDs.

In going from (0.6.4) to (0.6.5), the author downloaded

    dists/Debian3.1r0/main/binary-i386/Packages.gz
    dists/Debian3.1r0/main/source/Sources.gz

unpacking them with gunzip(1).

The Sources file is not strictly necessary, incidentally, but it
sometimes proves useful in helping to explain the build-dependencies
among the archive's various packages.

2.  Create a `debram/' working directory.

3.  Copy `debram_0.6.4.dsc', `debram_0.6.4.tar.gz' and the Packages and
Sources file into the `debram/' working directory.

4.  Give the commands

    $ cd debram
    $ for A in Packages Sources ; do mv -v $A{,.orig} ; done
    $ dpkg-source -x debram_0.6.4.dsc
    $ cp -av debram-{0.6.4,0.6.5}
    $ cd debram-0.6.5

5.  Create a working Packages file which includes additional
Ramification information by

    $ helper/new-debram-body -P ../Packages.orig >../Packages

NOTE RE THE FOLLOWING STEPS:  The order of steps 6 through 12 does not
matter.  They can be done concurrently in any order.

6.  Do not worry about updating version numbers and release dates in the
various source files: helper scripts are provided which will do this for
you automatically later.  Also do not worry about updating the
`debian/changelog' yet.

7.  Observe that the new working Packages file includes
a "Ramification: " line for each package ramified in debram.txt.  Edit
these lines as needed or desired.  Add new "Ramification: " lines for
packages which lack them.  Note that you need not (and probably should
not) type out the full ram title on a "Ramification: " line; the ram
number suffices.  For example, if you found that `bsdutils' were
misramified with

    Ramification: 6100 GAME PROGRAMMING

you would correct this to read

    Ramification: 5000

You would not waste time typing out "STANDARD UTILITIES AND FILES".

Do not actually move package lines around in the body of the
`debram.txt' file.  A helper script is provided which will do this for
you automatically in a later step, based on the changes you make now to
the working Packages file.

(It is a permissible alternative to edit the `debram.txt' file directly,
incidentally, dispensing with the working Packages file.  For most
updates such direct editing is harder and more complex.  However, for
some updates---not most, but some---the author himself does edit
directly; so, despite advice to the contrary, if you want to edit
directly, then you might read through the lengthy comments at the head
of `helper/new-debram-body'.  That script can help you.  Note that for
historical reasons `debram.txt' is encoded in iso-8859-1---a convention
you must follow unless you wish to undertake the wholesale conversion of
the source code to utf-8.)

8.  At the head of debram.txt, in the "RAMIFICATION MAP AND TABLE OF
CONTENTS", add, delete or modify ramifications and ram titles as needed.
(Do not do this lightly.  The typical debram update will not alter the
ramification map at all.  However, sometimes it may be necessary to make
a small correction or addition.  Once in a long while it may be
necessary to reform the entire ramification.)  Make the corresponding
changes at the foot of the file under "CROSS-REFERENCE (SEE ALSO)" and
in the main body of the file.  In the main body, it is not necessary to
give an accurate count of packages after each ram title; just put
a "(0)" there (the helper scripts will fix this for you automatically
later).

9.  At the foot of debram.txt, under "CROSS-REFERENCE (SEE ALSO)", add,
delete and/or edit cross references as needed or desired.

10. Add new maintainers to `maint.txt' and otherwise edit the file as
needed or desired.

11. Modify the various other source files as needed or desired.  Note
that users of debram (0.6.4) (released with sarge) have been promised
that later debram-data (0.6.x) binaries would work with their existing
debram (0.6.4) binaries.  You probably should not break this
compatibility (if NMUing, you really probably should not break it).  If
you do break it for some reason, you must number your new version at
least 0.7.

12. (This step is not very important.  You can safely skip it.)  If a
new year has turned since the last debram update, manually edit the
copyleft date "2002-2005" (or whatever it currently is) to reflect the
new year.  Do this in `helper/DescLoc' and in each of the several other
files referenced therein (probably debram.1, debram.txt and
debian/copyright)---but not in `cmdsel.txt', unless you are actually
updating that file.

NOTE RE THE FOLLOWING STEPS:  In general, unlike as steps 6 through 12
above, the order of the following steps does matter.  Nothing prevents
you from varying the steps and their order as needed, naturally, if you
understand basically what the steps do.  If unsure, however, follow the
steps in order.

13. Return to the `debram/debram-0.6.5/' directory, if you are not still
in it.

14. Give the commands

    $ helper/update-ver '0.6.5'
    $ helper/update-date '3 Oct 2005 21:00'

(substituting the correct new version number and release date for those
in the example).  These scripts format and update the version number and
release date (and time) as appropriate in various places about the
source, including the man page and the changelog.  For correct changelog
handling, you must invoke the scripts in the order indicated, and you
must invoke `helper/update-ver' exactly once (if you accidentally invoke
it more than once, it's no disaster, but you'll have manually to remove
the extra stanzas the script adds to the changelog's head).

On the other hand, after `helper/update-ver', you can safely invoke
`helper/update-date' as many times as desired.  Only the date you give
the last time you invoke the script matters.  (This is useful if you
aren't sure yet what the issue date should be.  You can guess now, then
give the right date later.)

The `helper/update-date' script assumes that you are entering the time
in UTC.  This is what the author does.  If you want to do otherwise,
you'll have to modify the script or otherwise handle the matter
yourself.  If and only if your update is specifically associated with
one of the daily 20:00-UTC Debian archive updates, you should use the
date of the archive update and the time 21:00.  Otherwise choose a
convenient date on or near the day of your upload and (if you have no
reason to do otherwise) use the time 00:00.

15. Canonicalize `maint.txt' by

    $ helper/sort-maint <docdata/maint.txt >/tmp/maint.txt
    $ mv -v {/tmp,docdata}/maint.txt
    $ helper/check-maint-addr docdata/maint.txt ../Packages

If the check script complains, fix the problem then run the check script
again.

16. Check the consistency of the ramifications, their titles and their
cross-references by

    $ helper/check-ram-titles
    $ helper/check-ram-titles -s
    $ helper/find-cmdsel-dupes

If the check script complains, fix the problem then run the check script
again.  (It surprises the author how often this check script catches an
error of some kind.)

Note that the script wants a ram's several cross-references in a
peculiar order: first refs to other rams within the local group of 10;
then to other rams in the local division of 100, then to other rams in
the local section of 1000; then, subject to these constraints, in
ascending numerical order.  For example,

    8888 Foo ---> 8882 8885 8820 8821 8850 8511 1111 2222 3333 9999

The debram(1) binary automatically prepends an implicit reference to the
ram's parent 8880, so the parent should not be listed explicitly.

17. Create a new debram.txt from the existing one and the working
Packages file by

    $ helper/new-debram-body -T ../Packages >/tmp/debram.txt

Skim `/tmp/debram.txt' to ensure that it looks as you would expect and
seems correctly to reflect the edits you have made in the working
Packages file.  When satisfied,

    $ mv -v {/tmp,docdata}/debram.txt

18. Expand unnecessary tabs and remove stray line-ending blanks by

    $ helper/buffe-src

Then, for good measure, invoke the scripts

    $ helper/check-ram-titles
    $ helper/check-ram-titles -s
    $ helper/find-cmdsel-dupes

again.

19. Run

    $ cd ..
    $ diff -ruN debram-{0.6.4,0.6.5} >debram-0.6.5.diff

Review debram-0.6.5.diff carefully to ensure that the new source
includes the changes you want and no others.  Observe that
`debram-0.6.5/debian/changelog' has an automatically generated dummy
entry atop it for the new version.  Correct this according to what you
see in the .diff.  After completing the changelog, if desired, run the
diff command again to get a complete .diff which reflects the new
changelog entry.

20. Test-build the revised package with

    $ cd debram-0.6.5
    $ dpkg-buildpackage -rfakeroot -uc -us
    $ fakeroot debian/rules clean
    $ cd ..

21. Install the revised package on your own system and see if it does
not seem to work as expected.  If it does, if you are otherwise
satisfied, if you feel ready to upload, then proceed to build the
package with pbuilder(1) or however else you usually build official
packages for upload, run lintian/linda, etc., then upload.

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

A CONDENSED RECIPE FOR UPDATING DEBRAM

It is unclear whether the following would interest anyone but the
author.  Nevertheless, here it is---for the author's own reference if
for no one else's.

Given shell parameters like

V0=0.6.4              # the old version number
V=0.6.5               # the new version number
DT='3 Oct 2005 21:00' # the release date and time

here is a general recipe, probably not to be followed literally, which
concentrates most of the steps above:

cd debram
for A in Packages Sources ; do mv -v $A{,.orig} ; done
dpkg-source -x debram_$V0.dsc
cp -av debram-{$V0,$V}
cd debram-$V
helper/new-debram-body -P ../Packages.orig >../Packages
# (Steps 6 through 12 go here.)
helper/update-ver $V
helper/update-date "$DT"
helper/sort-maint <docdata/maint.txt >/tmp/maint.txt
mv -v {/tmp,docdata}/maint.txt
helper/check-maint-addr docdata/maint.txt ../Packages
helper/check-ram-titles
helper/check-ram-titles -s
helper/find-cmdsel-dupes
helper/new-debram-body -T ../Packages >/tmp/debram.txt
mv -v {/tmp,docdata}/debram.txt
helper/buffe-src
helper/check-ram-titles
helper/check-ram-titles -s
helper/find-cmdsel-dupes
cd ..
diff -ruN debram-{$V0,$V} >debram-$V.diff
diff -ruN debram-{$V0,$V} >debram-$V.diff
cd debram-$V
dpkg-buildpackage -rfakeroot -uc -us
fakeroot debian/rules clean
cd ..

This recipe looks like a script, but it isn't quite.  Several of the
steps require preparation, thought, extension and/or modification,
depending on the sort of update you are trying to do.  Too many
alternatives and options seem to exist for one to transform the recipe
with reasonable effort into a sensible script which would help rather
than hinder development (the scriptable parts have already been
scripted; that's what all those `helper/' scripts are about).
Nevertheless, once you have some experience updating debram, you may
find the condensed recipe useful as a skeleton about which to organize
your own debram update work.  Anyway, this is what the author uses the
recipe for.