cvs: pearweb /sql design.txt

ssb Fri Jul 14 07:06:13 2000 EDT Added files: /pearweb/sql design.txt Log: * design document Index: pearweb/sql/design.txt +++ pearweb/sql/design.txt PEAR BACKEND DATABASE DESIGN $Id: design.txt,v 1.1 2000/07/14 14:06:13 ssb Exp $ 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 hte "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 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 xmlns="http://xmlns.php.net/pear/packagedesc" 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> <DestDir>DB</DestDir> <Dir>foosql</Dir> <File>foosql.php</File> <Dest>DB/foosql</Dest> <File>regtest.php</File> <DestDir>DB</DestDir> <DocFile Format="text/xml">foosql.xml</DocFile> <DocFile Format="text/html">foosql.html</DocFile> </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.