AEP: 12 Title: Archive Format and Revisions Version: $Revision: 1.0 $ Last-Modified: $Date: $ Author: Federico Di Gregorio Status: Draft Type: Standard Track Content-Type: text/plain Created: 24-Sep-2002 Post-History: Abstract This document explains the format (directory layout) of an arch archive (protocol version 2), how revisions are managed, including locking. Rationale No rationale: this document describe the core of the Arch protocol. Arch revisions An arch revision has the following format: archive/version%patchlevel where archive and patchlevel are optional. Archive is the archive name (not location) and has the following format: name@domain--spec where "name@domain" must be a valid email address, and "spec" is an optional alphanumeric word (see AEP 10 for some examples.) Version is an relative path starting after the first '/', just after the archive name and ending at (but not including the) '@' sign. (Both the '/' and the '@' are separators.) Patchlevel is just a number, starting from 0 and growing up as new patchsets are added (checked-in) to the version. Here are some examples, leaving out the archive part: linux--2--4--20--pre1 linux--2.4.20--pre1 psycopg--release--1--0%23 arch--devo--1.0%123 The only limitation is that a part of a version name can not _start_ with one of the arch reserved characters: '+', '=', '{', and ',,'. E.g., yarch--1--0--+12 is not a valid version name. Archives An archive is just a directory tree with some special files and directories added (plus version and patches,obviously.) The topmost directory is called the archive ROOT and contains the following files and directories: .archive-version Contains the archive version string: protocol 2 string must be: "Arch archive directory, format version 2.". =meta-info This is a directory containing some meta-information on the archive: at now it contains the following files: name the archive's name README the archive README file Archives never get locked, only versions are (see below.) Versions A version is a set of correlated patch-sets, kept in a directory that can easily be derived from the version itself, by replacing -- by / (path separators.) If ROOT is the archive root, the version's main directory (VTOP) is: VTOP == ROOT/version For example, arch--devo--1--1 meta-data and patches are located in ROOT/arch/devo/1/1. Patch data is separated into single directories as follows: ROOT/version/%0 -> base version ROOT/version/%1 -> patch level 1 ... ROOT/version/%N -> patch level N The following files are installed as meta-information: ROOT/version/=README readme for this version Locking Locking is based on assumption that version directories can never be deleted and that all the data reside in the patch directories. We also suppose directory creation, removal and rename are truly atomical operations. If this is the case it is not necessary to lock every directory from the top of the tree down to the wanted version but it do suffice to create a lock directory right into the requested version. If the directory cannot be created, someone else is locking it. The lock directory can be used to store transactional data during commits (see AEP xxx) and its name is +version-lock. Creating a new version is a little bit more complicated, because it is necessary to create the new directory _and_ lock it at the same time (to write meta information, for example.) This is accomplished by creating all the intermediary directories without locking (ignoring errors due to directories already existing) and creating the last directory with a temporary name, filling it then moving it in place. If the move fails the directory already exists, someone created the version before. Lock stealing If a process dies without unlocking a version the risk is to have that version locked undefinitely, so there is need for a way to unlock a directory. +transaction. References No references. Copyright This document has been placed in the public domain. Local Variables: mode: indented-text indent-tabs-mode: nil sentence-end-double-space: t fill-column: 72 End: