diff --git a/TODO b/TODO index c678f3cd..755e53ab 100644 --- a/TODO +++ b/TODO @@ -77,7 +77,7 @@ Legend: / documentation / actionsAPI documentation, unittests (caglar - meren) - / versioning information document + + versioning information document * medium priority diff --git a/doc/mails/[Cekirdek] [PISI design] release hikayesi b/doc/mails/[Cekirdek] [PISI design] release hikayesi new file mode 100644 index 00000000..9fb1b4e6 --- /dev/null +++ b/doc/mails/[Cekirdek] [PISI design] release hikayesi @@ -0,0 +1,110 @@ +From eray@uludag.org.tr Thu Jul 28 16:42:47 2005 +Return-Path: +X-Original-To: eray@uludag.org.tr +Delivered-To: eray@uludag.org.tr +Received: from liste.uludag.org.tr (pisi.uludag.org.tr [193.140.100.210]) + by uludag.org.tr (Postfix) with ESMTP id 0CE2C75758; + Thu, 28 Jul 2005 16:43:24 +0300 (EEST) +Received: from pisi.uludag.org.tr (localhost [127.0.0.1]) + by liste.uludag.org.tr (Postfix) with ESMTP id 2FD2D109DF1; + Thu, 28 Jul 2005 16:40:43 +0300 (EEST) +X-Original-To: cekirdek@liste.uludag.org.tr +Delivered-To: cekirdek@liste.uludag.org.tr +Received: from uludag.org.tr (comar.uludag.org.tr [193.140.100.220]) + by liste.uludag.org.tr (Postfix) with ESMTP id B4AAA109DDB + for ; + Thu, 28 Jul 2005 16:40:40 +0300 (EEST) +Received: by uludag.org.tr (Postfix) + id 5D432858B5; Thu, 28 Jul 2005 16:43:21 +0300 (EEST) +Delivered-To: cekirdek@uludag.org.tr +Received: from [192.168.1.5] (unknown [85.99.19.56]) + by uludag.org.tr (Postfix) with ESMTP id CC4ED75758 + for ; Thu, 28 Jul 2005 16:43:19 +0300 (EEST) +From: Eray Ozkural +Organization: Pardus +To: cekirdek@uludag.org.tr +Date: Thu, 28 Jul 2005 16:42:47 +0300 +User-Agent: KMail/1.7.2 +MIME-Version: 1.0 +Message-Id: <200507281642.47792.eray@uludag.org.tr> +Cc: +Subject: [Cekirdek] [PISI design] release hikayesi +X-BeenThere: cekirdek@liste.uludag.org.tr +X-Mailman-Version: 2.1.5 +Precedence: list +Reply-To: cekirdek@uludag.org.tr +List-Id: cekirdek.liste.uludag.org.tr +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +Content-Type: multipart/mixed; + boundary="===============1945860385==" +Sender: cekirdek-bounces@liste.uludag.org.tr +Errors-To: cekirdek-bounces@liste.uludag.org.tr +X-UID: 1875 +X-Length: 4330 + +--===============1945860385== +Content-Type: text/plain; + charset="us-ascii" +Content-Transfer-Encoding: 7bit +Content-Disposition: inline + +selamlar, + +dun konustuklarimiz uzerine biraz yatip dusundum. bir ara haci +kuslugu yapmisim ben de ve bir durumu gozden kacirmisim. +dun caglar ve murat'in getirdigi 2. oneriyle karisik bir sey yapmamiz +gerekebilir. benim kafam mi dagilmis ne kusura bakmayin. ama +o kadar onemli degil. + +soyle bir sorun var. + +simdi bir source var x diye, 5. release'de + +icindeki sadece bir paketi ornegin x2'yi etkileyecek bir degisiklik yaptik. + +bu durumda x1 ve x3'un build numaralari artmiyor. ama source release +numaralari mi artiyor? tamam buraya kadar ok. ama build sistemi +bu paketlerden yeni bir paket dosyasi yapip repository'e koymuyor bu +durumda, yani source release'i arttigi halde build nosu degismedigi icin +yeni paket koyulmayacak ve indekslenmeyecek bu mantikli mi? mantikli +degilse nasil bir cozum bulunur? + +bunun yani sira, simdi bu source release degistiginde, eger paketi build +*edersek*, bir yerde metadata degismek zorunda degil mi? hangi source'un +hangi release'inden build edildigini kaydetmek zorundayiz yanlis mi +dusunuyorum. hemen kizmayin butun bu olaylari basimiza ben sarmadim, bir +sekilde evrimlesti :) + +not: galiba olay suna geliyor, tamam build no degismediyse ozunde bu paket +bir onceki source release'inde kalmistir deriz, yani yeni bir dosya kesinlikle +koymayiz repository'e cunku install dosyalari ve metadata, release numarasi +disinda ayni kalacak. offffff. + +su anda multiple repository olayinin ilkel versiyonunu kodluyorum bu arada. + +gorusuruz, + +-- +Eray Ozkural (exa), Uludag Gelistiricisi +http://cekirdek.uludag.org.tr/~eray http://www.kde.org +http://www.cs.bilkent.edu.tr/~erayo http://www.malfunct.com + +--===============1945860385== +Content-Type: text/plain; charset="iso-8859-9" +MIME-Version: 1.0 +Content-Transfer-Encoding: quoted-printable +Content-Disposition: inline + +_______________________________________________ +Cekirdek mailing list +Cekirdek@uludag.org.tr +http://liste.uludag.org.tr/mailman/listinfo/cekirdek + +--===============1945860385==-- + diff --git a/doc/mails/[Cekirdek] source release ve binary build numaralari b/doc/mails/[Cekirdek] source release ve binary build numaralari new file mode 100644 index 00000000..345de3e2 --- /dev/null +++ b/doc/mails/[Cekirdek] source release ve binary build numaralari @@ -0,0 +1,125 @@ +From eray@uludag.org.tr Tue Jun 28 18:49:13 2005 +Return-Path: +X-Original-To: eray@uludag.org.tr +Delivered-To: eray@uludag.org.tr +Received: from uludag.org.tr (localhost [127.0.0.1]) + by uludag.org.tr (Postfix) with ESMTP id 80D2653C00C; + Tue, 28 Jun 2005 16:07:58 +0300 (EEST) +X-Original-To: cekirdek@uludag.org.tr +Delivered-To: cekirdek@uludag.org.tr +Received: from [192.168.3.131] (unknown [193.140.73.11]) + by uludag.org.tr (Postfix) with ESMTP id 0B6B753C00C + for ; Tue, 28 Jun 2005 16:07:57 +0300 (EEST) +From: Eray Ozkural +To: cekirdek@uludag.org.tr +Date: Tue, 28 Jun 2005 15:49:13 +0000 +User-Agent: KMail/1.8.1 +MIME-Version: 1.0 +Message-Id: <200506281549.13525.eray@uludag.org.tr> +Subject: [Cekirdek] source release ve binary build numaralari +X-BeenThere: cekirdek@liste.uludag.org.tr +X-Mailman-Version: 2.1.5 +Precedence: list +Reply-To: cekirdek@uludag.org.tr +List-Id: cekirdek.liste.uludag.org.tr +List-Unsubscribe: , + +List-Archive: +List-Post: +List-Help: +List-Subscribe: , + +Content-Type: multipart/mixed; + boundary="===============2126904290==" +Mime-version: 1.0 +Sender: cekirdek-bounces@liste.uludag.org.tr +Errors-To: cekirdek-bounces@liste.uludag.org.tr +X-UID: 865 +X-Length: 4347 + +--===============2126904290== +Content-Type: text/plain; + charset="us-ascii" +Content-Transfer-Encoding: 7bit +Content-Disposition: inline + +yigitler, + +bu post'da dun tartistigimiz bir konuyu ilgilendiren +paket versiyonu numaralarina tam bir aciklik getirmeye +calisacagim. + +Bir PISI source'u uc tane sayiyla belirlenir: + name, version, release + +Burada version "convenience" icin bulunur. name + release +ise her zaman *ayni* PISI source build islemine sebep olur. +Bundan kasit su. version ve release tamamen bagimsiz. +release 0 ile baslar. ornegin kdevelop + +ilk basta +name: kdevelop, version: 3.4.1, release: 0 +dir + +Bu paketin yeni versiyonlariyla biz ugrastikca, yaptigimiz +her update, en minikleri dahi, release'i arttirir, ve her zaman +bir arttirir (daha aciklayacagim), ama hic bir zaman geriye +gitmez (0'lanmaz ornegin). + +ileride: +name: kdevelop, version: 3.4.2, release: 3 +olabilir ornegin. + +Eger paketin gelistirildigi *distribution* source'u dahilinde +bir versiyon dallanmasi varsa, ancak bu durumda release'e +branch'ler eklenir. + +Diyelim ki yukaridaki paket pardus 1.0'in parcasiydi. simdi +pardus 1.0.1 diye bir branch olusturulmak istendi, ornegin +bu UEKAE overlay'ine karsilik gelsin. Bu durumda, versiyon +iliskisini eksiksiz bicimde belirtmek icin: +name: kdevelop, version: 3.4.2, release: 3.1 + +demek yeterli olacaktir. Ekledigimiz '.1' suffix'i bize butun +dal bilgisini verir. Boylece eksik hicbirsey olmaz. + +Binary package'lara gelince. Bir binary package dort +stringle her zaman bulunabilir. + name, version, build, architecture + +burada name + build, *bir binary distribution* dahilinde, +ornegin Pardus 1.0 x86 icin yapilmis tek ve tek bir paketi +her zaman gosterir. + +Build, o architecture icin, o paketin kacinci kere build +edildigini gosterir. Her paket release'inde en fazla bir +artar. + +Bunu daha once tartistigimiz gibi tamamen incremental +build script'inin buldugu md5'larla hesapliyoruz. + +Binary package'larin build numarasi icin bir dallanma/budaklanma +semasi henuz onermiyorum, ama bana su anda ayni +source package'lar gibi birsey yapilabilir geliyor. Bana buradaki +en kritik mesele source ve binary package'larini, ve upstream +version string'lerle kendi, SVN-tarzi version string'lerimizi +karistirmamamiz. + +Kaplan gunler, + +-- +Eray + +--===============2126904290== +Content-Type: text/plain; charset="iso-8859-9" +MIME-Version: 1.0 +Content-Transfer-Encoding: quoted-printable +Content-Disposition: inline + +_______________________________________________ +Cekirdek mailing list +Cekirdek@uludag.org.tr +http://liste.uludag.org.tr/cgi-bin/mailman/listinfo/cekirdek + +--===============2126904290==-- + diff --git a/doc/package_versions.tex b/doc/package_versions.tex index 6d214ed4..f7673a6a 100644 --- a/doc/package_versions.tex +++ b/doc/package_versions.tex @@ -1,18 +1,66 @@ \documentclass[a4paper,11pt]{article} -\title{P\'IS\'I Packages: Version Policy} +\title{P\.IS\.I Packages: Version Policy v0.2} \date{\today} -\author{T. Bar\i{}\c s Metin} +\author{Eray \"Ozkural and T. Bar\i{}\c s Metin} + + \begin{document} \maketitle +\section*{Revision History} +\begin{itemize} +\item v0.1: Bar\i\c s Metin wrote the first version preparing the outline, +detailed Source Version Section, and started the Section on Release Number. +\item v0.2: Eray \"Ozkural wrote a detailed introduction, added + explanations of release and build numbers, reorganized a bit. +\end{itemize} + \section{Introduction} -We'll document the \emph{version policy} that applies to the P\'IS\' -packages. +This document explains the \emph{version policy} that applies to +P\.IS\.I packages. Classically, the issue of distinguishing source and +binary distributions unambiguously has not received a rigorous +treatment in the context of LINUX distributions. We have identified +several shortcomings of the usual practices of extending the original +version with suffixes and prefixes, colorfully illustrated in the +following common problems. -\section{Source Version} +\begin{description} + +\item[The problem of future downgrades] +The distribution chooses to use a previous version of the package in +the next release. There is no way to indicate this, so ad-hoc +solutions such as version prefixes are used. It is +impossible to denote a future dependency that requires at least this +distribution source release in this case, either. + +\item[The problem of redundant distributions] +A trivial patch has been applied to the source. While few binary +packages have been affected by this change, all binary packages +built from the source are redistributed. + +\item[The problem of underdetermined rebuilds] +There have been rapid changes in the system, and although no +changes have been made to the package source, a new binary +distribution must be prepared. + +\end{description} + +We have devised a slightly new approach in order to alleviate these +problems. Our solution consists of encoding the history of source and +binary package developments in separate version strings we call release and +build numbers. + +Since the source version is usually used by the users and developers +to identify software, we retain the notion of a source version in +P\.IS\.I as a convenience. + +In the following sections, we explain the components of our +versioning scheme. + +\subsection{Source Version} Source version is the version number provided is provided by the upstream maintainer of the source archive used in package. It must be @@ -21,7 +69,7 @@ always the same as the upstream version used. \textbf{Example}: If the upstream archive name is \emph{bash-3.0.tar.gz} the version number of the package is \emph{3.0} -\subsection{Version Suffixes} +\subsubsection{Version Suffixes} There is a pre-defined list of suffixes a package version can take. @@ -43,19 +91,91 @@ suffix. \textbf{Example}: packagename-1.0\_beta1 The basic order of the priorities for suffixes is:\newline \emph{p $>$ (no suffix) $>$ rc $>$ pre $>$ beta $>$ alpha}. +The scope of a source version string is global in the literal +sense. -\section{Release Number} +The support for these special suffixes as well as usual alphanumeric +version string ordering has been implemented in P\.IS\.I. -Release number is the number of the changes that is made to the -package source. A change can be a patch applied to the source archive, -modification in the actions.py, pspec.xml or any file in the source -package directory. +\section{Identifying Package Sources} -\emph{Detailed explanation is needed} +A PISI source has three identity elements written under +\texttt{SOURCE} tag: name, source version, and source release number. +We usually say just version and release number/release instead of +source version and source release number, respectively. Name is available in +the \texttt{} tag. Version and release are available in the last +\texttt{} element of \texttt{} tag. + +The name of a source package is constant throughout its revision +history. The version is the original version, given by its +programmers. Release is a nonnegative integer. Name and release is sufficient to uniquely identify a +particular PISI source revision. That is, version and release are +independent. + +\subsection{Release Number} + +Release number is the number of the changes that are made to the +package source since the initial version in the distribution source. A +change can be a patch applied to the source archive, modification in +the actions.py, pspec.xml or any file in the source package +directory. This change is indicated in \texttt{} tags manually +by the package maintainer. + +The initial release of a package is by default \texttt{0}. The release +number always increments by $1$ in each revision in the +\texttt{History}, even the slightest ones, but it never decrements. + +The scope of the release number is a given distribution, regardless of +its version, e.g. Pardus. + +In the near future, PISI will have strict checks for release numbers. + +\subsection{Dependency Specifications} + +We allow a package to use both source version and release to identify +a particular or a range of package versions. + +\section{Identifying Binary packages} + +A PISI binary package is produced from a PISI source package. It has a +name that is constant throughout the history of the source package, +and it inherits the source version and release number from the source +package. However, a binary package has in addition a binary build +number. Shortly, build number or just build. For each of the +architecture targets, e.g. particular binaries, it also has an +architecture tag. + +A binary package is uniquely identified by its name, build number, and +architecture regardless of the source version. \section{Build Number} -\emph{Detailed explanation is needed} +Similarly to source release number, binary build number is the number +of changes that are made to a binary package. By change, we mean any +bit change. The existence of a change is tested by comparing the +cryptographic checksums in files.xml with the previous build, and the +build number is automatically determined by the P\.IS\.I build system. +The user never interferes with the build number himself. However, if +the user fails to provide the previous build, then a package without +a build number is built. + +The scope of a build number is a given distribution build environment +for a particular architecture. Therefore, it is not used in dependency +specifications. + +\section{Package File Names} + +A P\.IS\.I binary package file name contains all the components relevant +to its identification, separated by dashes: +\begin{verbatim} + ---.pisi +\end{verbatim} + +\section{Future Work} + +In the future, it may be necessary to extend the notion of release +number and build number to support branches and forks of a +distribution. A proposal was to have CVS-like branching. \end{document}