[lucy-dev] README/CHANGES and host-specific distro archives

[Marvin Humphrey <ma...@rectangular.com>]

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

Re: [lucy-dev] README/CHANGES and host-specific distro archives

[Peter Karman <pe...@peknet.com>]

Marvin Humphrey wrote on 3/30/11 7:49 PM:

> 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.
> 

+1 to all of the above


> 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.


+1

-- 
Peter Karman  .  http://peknet.com/  .  peter@peknet.com