#------------------------------------------------------------------------------
       Idea to Support Maintenance of Localized CRUX Packages' Files

The pkgutils are at present of little use for supporting file localizations.
Thus the sysadmins must develop and implement SOPs for localizations of
installed files on their own.  Note the scope of such localizations is clear
text (configuration files, interpreted scripts, man pages, and the like)
registered in /var/lib/pkg/db.

The /etc/pkgadd.conf facility only prevents the overlay of localized files
by package updates.  The rejmerge tool cannot provide clear diffs between
installed and rejected files when the installed file has been localized.
The pkgrm tool will not do anything to preserve localizations for future
redeployments.

While this proposal may not be adequate for many, perhaps most, current CRUX
deployments, it at least could be used out of the box to begin managing such
changes with an eye toward tracking them, simplifying their updates as their
packages evolve, and preventing loss of such modifications.  For new CRUXers
it may be a solid basis for their own localization SOP developments.  Note
these extensions are entirely optional and do not modify the CRUX 3.6
behaviors of pkgutils in any way where the extensions are inactive, the
default situation.

This design formally postulates two states of any CRUX installable file in
addition to installed and rejected: localized and canonic, which are mutually
exclusive.  Rejected files are inherently canonic.  Installed files usually
start out canonic but may be localized by the sysadmin as needed to make the
file fit for the purposes of the CRUX system being maintained.

The CRUX 3.6 pkgutils behavior uses the /var/lib/pkg/rejected tree to "install"
those files blocked from normal installation by the configuration of rules in
the /etc/pkgadd.conf file.  When files are so rejected, that is considered
normal and not even announced.  It is expected the sysadmin will deal with
rejected files, perhaps using the pkgutils' rejmerge tool, such that the
changes contained in the rejected file are merged into the corresponding
protected file in the target filesystem.  Once that has been accomplished,
if it is indeed even necessary, the rejected file is then normally deleted
from the /var/lib/pkg/rejected tree so at the conclusion of rejmerge
processing, the rejected tree contains no files--any subdirectories contain
only directories or are empty.

The behavior of the localization enhancements is an alternative to the file
rejection behavior just described, and is triggered when pkgutils encounter
the existence of three peer directories to rejected in /var/lib/pkg:
  pendings
  canonics
  retained
which are subsequently used instead of rejected.  Thus, the presence of these
directories causes the rejection processing of pkgutils to be disabled--the
/etc/pkgadd.conf rules are always ignored as is the rejected directory if it
even exists.  Instead, pkgadd decides not to install a file from a package
when an installed version exists that not canonic--it has been localized.
It knows it is localized if a version of that file exists in the canonics
directory.  When the sysadmin decides to localize an installed canonic file,
the existing file is first copied into the canonics directory, thus keeping
the original package version around as well as indicating localization has
occurred (it is incumbant upon the sysadmin to use the rejmerge subcommand
for this purpose instead of just editing the file!).  When a pkgadd update
encounters the localized file, it diverts the new canonic file into the
pendings directory tree, which corresponds in purpose to the rejected
directory tree.  The retained directory holds copies of localized files that
have been superseded by newer localizations or have been removed by pkgrm
processing, needed to produce diffs of the different localized versions of a
file or to relocalize the file after a new canonic version has been
installed.

While all three new directory trees have the same structure as the rejected
directory, all use extended basenames for the files that use two formats:
  canonic:   installed_basename#port_version-release#package_file_mtime
  localized: installed_basename#mtime
Canonic filename extensions are used in the canonics and pendings directories
while localized filename extensions are only used in the retained directory.
Examples:
  /var/lib/pkg/canonics/etc/profile#bash#5.1.8-1#20210911_015123
  /var/lib/pkg/retained/etc/profile#20210913_123456
Note mtimes are in UT.  The metadata basename extentions enable multiple
pendings, canonics, and/or retained files for any particular installable file
to exist simultaneously instead of always replacing the existing file.  Also,
a symlink to the current pendings, canonics, and/or retained version of the
installable file can be maintained when useful; e.g.,

  profile -> profile#bash#5.1.8-1#20210911_235959

When an installed file is canonic, no versions of that file are maintained in
the canonics directory, which is how the canonic state of the installed file
is known.  The mtime of such files provide a clue for determining which
version it is, although it will normally be the version of the entire package
installed.  The definitive proof lies in querying the contents of the
available package files for the package looking for the file with matching
metadata.  If such proof cannot be unearthed, then the mtime can still
provide an idea of what package file it might have come from.

Thus, it is proposed that CRUX package maintenance can, by changes to the
pkgadd, pkgrm, and rejmerge executables (and their doc):
 1. Be aware of localizations of installed files
 2. Retain the canonic versions of localized files including the package
    name, version, release, and package tarball file's mtime metadata
 3. Report after pkgadd processing any new pendings files
 4. Extend the set of rejmerge subcommands to:
    A. Show diffs of a pendings file versus its current canonic file, whether
       that is in the canonics tree or its installed location
    B. Merge the diffs between the canonic and pendings files into the
       localized file
    C. Localize via $EDITOR an installed canonic file (first preserving the
       original in the canonics tree)
    D. Unlocalize a file (replace it with a canonic file, retaining it for
       future diffs and/or redeployment
    E. Relocalize an installed canonic file (replace it with a previously
       retained version)
    F. Cull no longer needed canonics, retained, or pendings files (possibly
       according to configurable automation)
    G. Reassign the current file (change the symlink of the current file to
       point to a different instance)
 5. Retain localized files during pkgrm processing
#------------------------------------------------------------------------------