[Gnu-arch-users] robin's per-directory regexps

[Tom Lord]

Hi.   I'm going through Rob's integration branch, starting to 
merge things in.

Currently I'm working on Robin's support for "per-directory naming
convention regexps".   

Briefly, these let you put a ".arch-inventory" file in a directory
which defines naming conventions that apply to that directory (in a
slightly subtle way).

Thanks especially to Robin for writing this and Rob for integrating it
-- it looks quite workable.

In reviewing the code, I've found a few problems.  I'd like to spark a
brief discussion.  Fixing one of the issues will break compatability
with people already using the patch.  Two issues raise minor upwards
compatability problems (so minor that I'm tempted to live with it but
I'll suggest an alternative).   It's probably worth going over
the proposed semantics one more time.



Here are the issues:

* the inventory tag of ".arch-inventory" files

  Robin's code always assigns a .arch-inventory file
  a tag of the form:

        ?relative/path/.arch-inventory

  This is a definate bug.   For example, if my tree has:

        ./src/headers
          ./src/headers/.arch-inventory
          ./src/headers/foo.h

  but in your tree you have renamed this to:

        ./src/include
          ./src/include/.arch-inventory
          ./src/include/foo.h


  then the two copies of the .arch-inventory file have 
  distinct tags.   Changes I make to mine will not be 
  applied to yours if you merge my changes.

  The right solution here, I believe, is to not have a 
  special rule for the tag of a .arch-inventory file.
  It should contain a tagline or be explicitly tagged.

  Correcting this bug, however, will break revisions 
  that already use the .arch-inventory patch.  


* .arch-inventory as control file

  The patch treats all .arch-inventory files as "control
  files" in the sense that if exclude files are not
  being excluded, then .arch-inventory is automatically
  a source file, no matter what the (non-exclude) regexps
  say.

  I think that that's basically the right thing to do.  Surely
  we don't want inventory to consult a .arch-inventory file
  for per-directory regexps but then _not_ treat that file
  as source.

  But there's an upwards compatability issue.  Suppose that
  someone already has a tree in which ".arch-inventory" is
  _not_ classified as source.   This change will change the
  semantics of `inventory' in that tree.

  For example, if we imagine that someone has a script which
  they use instead of `get';  the script gets the tree normally,
  but then traverses it, creating (for some mysterious reason)
  ".arch-inventory" files in each directory;  these files are 
  classified as "junk" by the regexps this tree uses.   

  Robin's patch will break that script.

  Now, I tend to think it is sufficiently unlikely that anyone
  is already using the name .arch-inventory as a non-source 
  file.   So I think I'm willing to go ahead and break upward
  compatability in that way.

  There are two alternatives that come to mind, that preserve upward
  compatability (but break trees already using the patch):

  One is to say that ".arch-inventory" files are only ever used if
  "./{arch}/=tagging-method" contains a special directive, say,
  "enable .arch-inventory".

  Another is to is to rev the "project tree version number" -- 
  a prospect I'm not too fond of.



* semantics review

  From the issue mail, it looks like people debated the exact
  semantics for .arch-inventory and came to a reasonable conclusion.
  I'd like to restate it for the list (as I understand it) and 
  also raise two new questions:

  .arch-inventory files can contain regexp declarations just like
  those in =tagging-method (i.e., one for `excludes', one for
  `junk', etc.)   Let's call these the "dir-local regexps".
  The =tagging-method regexps are the "global regexps".a

  While traversing a tree, each file is classified-by-name as follows.
  the steps which are changed by the patch are marked with "[*]":

        0) "." and ".." remain excluded files, no matter what.

   [*]  1) if excluded files are being omitted from the inventory,
           and either the dir-local or global regexp, the file
           is excluded

        2) if the file is a control file, it is source

        3) if the file falls into one of the "mandatory categories"
           (",," and "++" files) it is categorized as junk or 
           precious respectively.

   [*]  4) the dir-local (only) regexps are tried in the usual order:
           junk, backup, precious, unrecognized, source.  If the file
           matches, it is suitably categorized.

        5) the global regexps are tried in the same order.

        6) otherwise the file is unrecognized.


  The brief controversy in the issue discussions were about the
  special treatment of dir-local exclude, and about whether or not
  steps 4 and 5 should be combined:

        4-5 alternative)  both sets of regexps are tried in order:

                dir-local and global junk
                dir-local and global backup
                etc.

  Another alternative is:  if dir-local regexps are defined, the 
  global regexps are entirely ignored.

  I think that the arguments in favor of how Robin has done it are
  good.   For example, a .arch-inventory can contain _only_
  a "source" regexps, perhaps defining "core" as source -- that
  will override a global regexp that defines "core" as junk or
  precious.

  The idea of simply ignoring global regexps if dir-local ones are
  present is conceptually simpler, but I think less practical.  If
  eventually we want that, we can add an `unrecognized2' regexp
  keyword to .arch-inventory syntax, tested after the source regexp,
  so that:

        unrecognized2 .*

  will have the effect of causing global regexps to be ignored.

  Finally, the patch contains no provision for a .arch-inventory file
  which applies recursively to subdirs.   I'm not sure one is actually
  needed.  It's a little unclear how it would interact with a
  .arch-inventory file in a nested directory.   Nothing in the patch
  precludes adding this later if we really want it and have a clear
  idea of what it should do.


* Changes to the "ancient defaults"

  The patch changes the "ancient default regexps" to add
  .arch-inventory to the excludes regexps.

  This is, strictly speaking, a bug:

  The "ancient defaults" are used only if =tagging-method fails
  to define a particular regexp.    For example, if =tagging-method
  does not define any `excludes' regexp, then the ancient default
  is used.

  These days, `init-tree' sets up a tree so that all regexps are
  given default values in =tagging-method.   Consequently, except
  for very old trees, the ancient defaults aren't used at all.

  In some sense, the "ancient defaults" should remain stable
  _forever_, in order to retain perfect upward compatability with
  very old trees.

  However, I doubt that any of the very old trees will be bitten by
  this compatability change.  I also doubt that newer trees where
  someone has gone out of their way to delete the "excludes" regexp
  from =tagging-method will be bitten.

  So, as with the addition of .arch-inventory to the set of "control 
  files which are automatically source if not excluded", I'm willing
  to live with this incompatible change.

  The alternatives are the same:  rev the project tree format revision
  number or be sensative to an `enable .arch-inventory' directive in
  =tagging-method.


* other issues

  There are some other minor issues about code formatting and coding 
  style -- more a reflection of my quirky fussiness over some issues
  than anything else.


-t