h1. bzr filesystem layout
The current working propsal for the new Bzr repository structure.
h2. Introduction
Unlike Arch/TLA's cat--branch--N.N scheme, Bzr uses an arbitrary directory system. As we are in the process of migrating from Arch/TLA to Bzr, this is an opportunity to better structure the SCM repository to be more intuitive to the end user. Not to mention rework the layout to better fit future QA and Build/Release management plans. The repository structure is in no way a strict construct in bzr, and what exists in the pqm need not exist in any developer repositories. Branches need not even be named the same between repositories, or be in the same location. At the same time, maintaining some coherent level of consistency between branches helps to avoid unnecessary confusion. In the end, this proposal is capable of being changed at some future time should it prove to be insufficient to our needs.
h2. Patch Queue Manager
The Bzr SCM (Source Configuration Management) is a decentralized tool, allowing developers to maintain their own repositories of their changes. A developer is capable of making their own branches from any other repository, pull changes from any other developers branches, and making their own changes. All developer changes are tracked within their own repository as opposed to existing in a centralized location as is the case with SCM's like CVS and SVN. As Bzr does not maintain any clear distinction of a central repository authority, the burden is placed on the development community to declare some specific repository for this purpose, often the repository of some specific developer. In contrast the FMI/OS project has opted to delegate an automated repository to act as the centralized source authority. This repository is referred to as the PQM, or Patch Queue Manager.
The Patch Queue Manager is an SCM helper tool, written by Robert Collins, that facilitates the submission of changes from outside developers into the the PQM's repository. The basic mechanism is for a developer to send a OpenPGP signed email with PQM commands in the message body. The PQM software itself validates the OpenPGP signature against the PQM's keyring, if the signature is trusted, it places the commands into its queue. From there the PQM processes the queue in the order in which valid messages where recieved. The most common command to be issued is that of a merge request by a developer, informing the PQM to merge some changes from the developer's public archive into the PQM's archive. In order for this to be accepted the PQM software constructs a software checkout from its repository, and applies the merge. This is followed by an optional battery of tests to be run against the modified source code to validate that the changes satisfy all merge criteria. Such criteria can include build completion, regression testing, code formatting, bug fixes against a release branch, etc ... If all tested criteria pass, then the changes are commited into the PQM's local repository, and then pushed to a public mirror making the changes available to be pulled from other developers. If the merge or tests fail, an email is dispatched back to the submitter informing them of the failure. A merge failure typically is the result of a merge request being submitted by a developer whose repository is out of date in relation to the PQM's repository, i.e. some other developer merged in changes to the PQM earlier.
h2. Two Repositories
In keeping the likely need for dealing with package build and release, it has been proposed to utilize two repositories.
- source-pqm - Primary PQM controlled Source Code Repository
- build-pqm - Primary PQM controlled Build Control Repository
The top level entries in both the source-pqm and build-pqm repository is that of package categories:
- system-base - base system packages
- system-libs - system libraries
- system-utils - system utilities
- servers-fs - filesystem servers
- servers-hid - human interface device servers
- servers-net - network infrastructure servers
- servers-disc - disc device servers
- servers-char - character device servers
The second level structure is of the package names:
- system-libs/libc
- system-base/init
- servers-fs/dosfs
- ...
The third level entry is the package version and exists only in the source-pqm, as the build-pqm has no need of this entry:
- system-utils/foo/1.0
- system-utils/foo/2.0
- system-utils/foo/2.1
- system-utils/foo/dev
- ...
The dev entry in is a special version for core development. All other version branches are copies of the dev version made during various milestone points of the dev process. All packages will always have at least the dev version, even if they have no other released versions in the repository at all.
h3. source-pqm
The source-pqm is the repository where all software development occurs, primarily on the dev branch. The non-dev branches of a package primarily receive bugfixes, while enhancements to the package are handled in the dev branch.
h3. build-pqm
The build-pqm will contain build scripts that describe package dependencies, and build automation scripts describing how to build the package. This repository does not contain a version component as all dependencies and build rules are contained in a single file. Each file describes how to build a specific version of the package, thus a version branch is not necessary.
h2. Package Versioning
The hope is that future development for each package will follow a milestone path, where milestones are set for a specific release, and when the milestones have been achieved in dev, the branch will then be copied off to the release version for that package. At that point the package is considered released and no further enhancements will be allowed to the release branch, only bug fixes. Enhancements and such will be allowed to continue in the dev branch of the package.
Versions are divided into the Major and Minor version part. A release from 1.0 to 2.0 signifies that the 2.0 package is in some way incompatible with 1.0. Issues such as a total config file rework might signify an incompatibility version increment. A major version change does not necessarily imply that there are new major features in the release, though one would hope that there are.
A release version change from 2.0 to 2.1 signifies simple bug fixes and or compatible enhancements, but that the package itself is fundementally compatible across the change, i.e. it should be safe for a user to go from a 2.0 to 2.1 package version without any problems in the upgrade, whereas upgrading from a version such as 1.0 to 2.0 may require completely reconfiguring the package.
There is no idea of a third version, or the teeny version, in this scheme as we are only focusing on reflecting development within the source-pqm repository. A teeny version change, such as 2.0.0 to 2.0.1 is left as a part of release management from the build-pqm tree, as some aspects of release management may contain minor modifications to installation procedures and such that will not be reflected in the source-pqm. In order to facilitate maximum flexibility of the dev to release process, it has been tentatively chosen to leave decisions on the teeny version up to the build/release team.
h2. Package Management
While all source development occurs in the source-pqm, certifying and preparing packages occurs in the build-pqm. In the build-pqm a build rule file, called an ebuild, is written that points at the source for the package. It contains information about retrieving, configuring, compiling, and installing packages. The rule files contained in the build-pqm itself may reference any packages, not necessarily packages in the source-pqm.
h4. Comment by mabri on Wed Dec 6 10:01:01 2006
Why is the graph gone and where is the servers-misc package, please ?
h4. Comment by major on Fri Dec 8 02:59:25 2006
servers-misc should be in both my bzr repository and the source-pqm repository.
The graph is gone as I did it before writing the rest of the docs, and now I don't know of a sane way to put the graph back in without making things a bit more confusing.