Current File : //opt/RZphp72/includes/www/pear.php.net/sql/design.txt

		     PEAR BACKEND DATABASE DESIGN
	 $Id$

TERMINOLOGY

Author
	An author is a contributor to PEAR.  An author is usually
	referred with a name usually based on initials.  This name is
	the identifier used in the database and XML description files.

Domain
	A _domain_ is a section of the file namespace allocated to a
	package or a collection of related packages.  For example,
	"DB" is the domain for packages for database-independent
	connectivity.  Other domains may be "XML" or "Net/HTTP".

	A new domain may be created by the administrator of any parent
	domain.  New top-level domains are created by the
	administrator of the root domain.

Package
	A PEAR _package_ is a collection of C code (extensions) and
	PHP code within a certain _domain_.  Any number of packages
	can use the same domain.

Release
	A PEAR _package_ is made available through a _release_.  Each
	release has a version number (see version section below).

Distribution
	A package _distribution_ is the officially supported way of
	installing a package automatically.  The distribution is a
	gzip-compressed tar file with a file called "package.xml"
	within it describing the package.  See the "XML DESCRIPTION
	FILE FORMAT" section below for more details.

	There are two types of distributions: source distributions and
	binary distributions.  A binary distribution is one with only
	platform-indepdenent files (meaning no C code, only PHP code)
	or one where the C-code has been compiled for a specific
	platform (both debug and non-debug versions of the binary code
	should be included).  A source distribution contains only the
	PHP and C code.  The installer then needs to compile the C code.

DATA ENTITIES AND ATTRIBUTES

The first indent level represents entities, the second indent level
represents the attributes of that entity.  The "->" arrow represents a
foreign key (in principle, because some of them are circular, they
will not be implemented with "REFERENCES" in MySQL).

Aliases
	Package		-> Packages(Name)
	Alias		Varchar

Authors

	Handle		Varchar
	Password	Varchar
	Ppp_only        Integer (Is this account used for proposals only?)
	Name		Varchar
	Email		Varchar
	Homepage	Varchar
	Created		Integer (UNIX timestamp when created)
	Modified	Integer (UNIX timestamp when last modified)
	Createdby	-> Authors(Handle)
	ShowEmail	Bool (whether to show email address to the public)
	Registered	Bool
	Admin		Bool (an admin can create/accept new authors and
			      set domain adminsitrators)
	AuthorInfo	Text (additional info by the author)

Domains
	Domain		Varchar
	Administrator	-> Authors(Handle)

Packages
	Name		Varchar
	Domain		-> Domains(Domain) (also implied by Name)
	Originator	-> Authors(Handle)
	Maintainer	-> Authors(Handle)
	CurrentStable	-> Versions(Id)
	CurrentDevel	-> Versions(Id)
	Copyright	Varchar
	Summary		Text (short description)
	Description	Text (full description)

Versions
	Id		Integer
	Package		-> Packages(Name)
	Version		Varchar
	ReleaseDate	Integer (YYYYMMDD)
	ReleaseNotes	Text

XML DESCRIPTION FILE FORMAT

Each package _distribution_ contains a file called "package.xml".
This is an example package.xml file for the PEAR package "DB/foosql"
in a (binary) distribution file called "DB_foosql-1.1b2.tar.gz":

<?xml version="1.0" ?>
<Package Type="Binary">
 <Name>DB/foosql</Name>
 <Summary>
  DB/foosql is the DB backend for FooSQL.
 </Summary>
 <Maintainer>
  <Initials>SSB</Initials>
  <Name>Stig S. Bakken</Name>
  <Email>stig@php.net</Email>
 </Maintainer>
 <Release>
  <Version>1.1b2</Version>
  <Date>2000-07-14</Date>
  <Notes>
   Fixes a few bugs in the FooSQL backend.
  </Notes>
 </Release>
 <FileList>
  <Dir>DB</Dir>
  <File>DB/foosql.php</File>
  <File Role="test">DB/foosql/001.phpt</File>
  <File Role="test">DB/foosql/002.phpt</File>
  <File Role="test">DB/foosql/003.phpt</File>
  <File Role="doc" Format="text/xml">foosql-faq.xml</File>
  <File Role="doc" Format="text/html">foosql-faq.html</File>
 </FileList>
</Package>

All the files referred to in <FileList> can be found at the same
location in the tar archive.  Where these files are acually installed
is decided by the package installer, it will probably be configured to
put HTML docs, XML docs, binary code and PHP code in different
locations.

The contents of the distribution file would then be:

package.xml
foosql.php
regtest.php
foosql.xml
foosql.html

VERSIONING

It is strongly recommended that package maintainers select one of the
following versioning schemes:

    YYYYMMDD		(YYYY = year, MM = month, DD = day)
    V[{a,b}N]		(V = version) [ alpha or beta release N ]
    V.R[{a,b}N]		(R = release)
    V.R.P[{a,b}N]	(P = patchlevel)

PEAR tools follow these rules to compare versions:

For YYYYMMDD, V, R, P and N, a higher number indicates a newer
release.  Any beta of a release is considered newer than an alpha of
the same release.

When comparing V with V.N, V.N is considered newer if the version part
of V.N is greather than or equal to the version part of V.  The same
logic applies to V.N.P vs. V.N.

Releases with lots of known bugs, potential API changes etc. are
typically alpha releases.  Beta releases are when the risk of API
changes is minimal and you believe most bugs are found.