Mailing-List: contact lucy-dev-help@incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: lucy-dev@incubator.apache.org
Received-SPF: pass (athena.apache.org: local policy)
Date: Wed, 30 Mar 2011 17:49:34 -0700
From: Marvin Humphrey <marvin@rectangular.com>
To: lucy-dev@incubator.apache.org
Message-ID: <20110331004934.GA29728@rectangular.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.5.18 (2008-05-17)
Subject: [lucy-dev] README/CHANGES and host-specific distro archives

Greets,

The derived packages for our host language bindings -- i.e. the
tarballs/archives we upload to CPAN, PyPI, rubygems.org, etc -- will not have
the same directory structure as the official Apache Lucy source release.  They
will consist of the material within the host language dir, with other
essential top level dirs and files copied in:

  Official source release:
  
    LICENSE
    NOTICE
    README
    charmonizer/
    clownfish/
    core/
    devel/
    modules/
    perl/
        Build.PL
        lib/
        sample/
        t/
        ...
    ruby/
        Rakefile
        lib/
        sample/
        test/
        ...
    ...
    
  CPAN release:

    Build.PL
    LICENSE
    NOTICE
    README
    charmonizer/
    clownfish/
    core/
    lib/
    modules/
    sample/
    t/
    ...

Some files are going to present clashes because of this situation.

In the repository right now, we only have one README file, trunk/perl/README.
It contains traditional Perl module installation instructions, in addition to
a minimal description of the library.  I propose that we make the following
adaptations:

    * Move the perl module installation instructions into a new file,
      trunk/perl/INSTALL.
    * Add a new file trunk/INSTALL which instructs the user to chdir into
      the directory of their host language of choice and follow the
      instructions in the INSTALL document there.  This file would be omitted
      from the CPAN/PyPI/etc. archives.
    * Eliminate trunk/perl/README.  
    * Add trunk/README, which would contain a minimal description of the
      library, the incubation disclaimer, and a pointer to INSTALL.  This file
      would be copied (along with LICENSE and NOTICE) to the host language dir
      when preparing the host-specific distro archive.

We also have to consider how to handle change info.  Right now there is only
one CHANGES file: trunk/perl/Changes.  It contains almost nothing, since
we're starting fresh.  I propose we eliminate that file and create
trunk/CHANGES, which would record change info for all of Lucy, including all
bindings.  It would be copied along with README, LICENSE and NOTICE when
building a host-specific distro.

An omnibus CHANGES file will be marginally noisier for consumers of
host-binding-specific archives, but I hope that on the whole it will be less
troublesome for both devs and users than spreading change info across multiple
CHANGES files whose names conflict when it comes time to create the
host-specific archives.

Marvin Humphrey