mirrorrib for Debian
--------------------

This package's mirrorrib(1) program comes as a set of shell scripts
and, thus, can be run right where it already is, in the unpacked source,
without installation.  However, one must build etc/mirrorrib.conf first
and might build some other incidentals like the localization message
catalogs, too:  enter 'make' from the top directory to do these things.
After that, enter 'usr/bin/mirrorrib' (note: for uninstalled software,
it's 'usr/...', not '/usr/...') to run mirrorrib(1).

The normal way to handle mirrorrib, however, is to install its binary
package and then to run mirrorrib(1) as one would run any other
command-line oriented program.

MODIFICATION AND REBUILD

If you wish to modify and rebuild the package, then do approximately
the following:

1. Fetch the package's source to the current directory by 'apt-get
source mirrorrib'.  (Presumably, you have already done this or you
would not be reading these words.)

2. Substituting the version number for the "*", unpack the source
by 'dpkg-source -x mirrorrib_*.dsc'.  (Presumably, you have already
done this, too.)

3.  Again substituting for the "*", Rename the source
directory by 'mv -iv mirrorrib-*{,.1}'.  For
example, 'mv -iv mirrorrib-0.10.0{,.1}'.

4.  Change into the renamed source's top directory
with 'cd mirrorrib-*'.

5.  Update build.conf.

6.  Run 'debian/dev/extend-changelog' to add a dummy changelog entry.

7.  Modify the source as you see fit.

8.  Test the modified source as you see fit.

9.  Fill in the dummy entry in debian/changelog.  Because the filled
entry is yours, substitute your own name and address in that filled
entry for the maintainer's.

10.  Update build.conf again if you wish.  If you do, then
run 'debian/dev/extend-changelog --only-update-date' to update the top
changelog's date.

11.  Consult debian/control.  Ensure that not only the Debian
packages listed by 'Depends:' but also those listed by 'Build-Depends:'
are installed, along with the Debian package 'build-essential'.
Use 'sudo apt-get install PACKAGES...' to install missing packages.

12.  Change into the source's top directory if you are not
already there.

13.  Issue the command 'dpkg-buildpackage -tc --no-sign' to build the
modified Debian package.

14.  Exit the source by 'cd ..'.

15.  Find the rebuilt debian package in that directory.  Install it if
you wish by 'dpkg -i mirrorrib_*_all.deb'.

Many variations of the above procedure are possible, but if you are
unsure of how to start, then you can just follow the listed steps.

FUTURE DEVELOPMENT PLANS

Mirrorrib is a young program, first developed while Debian buster was
stable and Debian bullseye was testing.

Ideally, Mirrorrib would have gained Debian bullseye support before
bullseye had graduated to displace buster as stable.  However, from a
development perspective, the layout of Debian's testing archive is a
moving target.  To hit a moving target is hard -- especially when the
target is not a software package one can unpack and exercise.  Under
the circumstance, to wait until after bullseye graduates to displace
buster seems prudent.  Then, if it goes according to plan, support can
be added for both bullseye and bookworm at that time.

But won't the same problem then arise for bookworm?  Answer:  yes, it
will, but bookworm will be the *third* major version of Debian to be
supported, not the second.  The second bears the burden of adapting the
source to handle multiple versions, so the third should be easier.

Such is the plan, at any rate.

If you are running Debian bullseye stable, then look in backports for
an updated Mirrorrib that handles bullseye.  It should appear sooner
or later.

 -- Thaddeus H. Black <thb@debian.org>  Wed, 24 Feb 2021 00:00:00 +0000
