[maemo-commits] [maemo-commits] r16541 - projects/haf/doc/mvo

[From: subversion at stage.maemo.org]

Author: marivoll
Date: 2008-10-31 01:18:23 +0200 (Fri, 31 Oct 2008)
New Revision: 16541

Modified:
   projects/haf/doc/mvo/system-model-2.txt
Log:
Moved all the pending stuff into its own section.  The Maemo archive
is now completely public.  Other tweaks.


Modified: projects/haf/doc/mvo/system-model-2.txt
===================================================================
--- projects/haf/doc/mvo/system-model-2.txt	2008-10-30 16:54:49 UTC (rev 16540)
+++ projects/haf/doc/mvo/system-model-2.txt	2008-10-30 23:18:23 UTC (rev 16541)
@@ -95,19 +95,11 @@
 but people need to explicitly agree to certain conditions before they
 are allowed to download from other categories.
 
-Thus, categories control publishing of packages.  A package is made
-public by moving it to a category with general access (maybe subject
-to a anonymous license agreement).  This is different from releasing a
-version of Maemo.  See "Distributions", below.
-
 The categories are:
 
  nokia-free
- nokia-freely-distributable
+ nokia-non-free
  nokia-restricted
- nokia-free-pending
- nokia-freely-distributable-pending
- nokia-restricted-pending
  maemo.org-free
  maemo.org-non-free
 
@@ -119,14 +111,13 @@
  OSI approved Open Source license.  Everybody can access this category
  freely.  Only Nokia can upload to it.
 
- - nokia-freely-distributable
+ - nokia-non-free
 
- Packages in nokia-freely-distributable are not Free Software, but
- they can be redistributed freely.  Some have source, others don't.
- Everybody can access this category freely.  Only Nokia can upload to
- it.
+ Packages in nokia-non-free are not Free Software, but they can be
+ redistributed freely.  Some have source, others don't.  Everybody can
+ access this category freely.  Only Nokia can upload to it.
 
- - nokia-restricted 
+ - nokia-restricted
 
  Packages in nokia-restricted are not Free Software and can not be
  redistributed freely.  Access to this category is granted after
@@ -139,31 +130,6 @@
  allowed to distribute their binaries with the license agreement of
  nokia-restricted.
 
- - nokia-free-pending
-
- Packages in nokia-free-pending are Free Software suitable for
- nokia-free that have not been published yet.  Reasons for holding
- back free packages from being published can be incomplete legal
- checks and the desire to keep them a trade secret until some launch
- event.
-
- New packages that are destined for nokia-free could be forced into
- nokia-free-pending instead.  Legal checks can be triggered by a new
- package appearing in nokia-free-pending.  Packages could
- automatically move to nokia-free once the check is complete.
-
- - nokia-freely-distributable-pending
-
- Packages in nokia-freely-distributable-pending are suitable for
- nokia-freely-distributable that have not been published yet, similar
- to nokia-free-pending.
-
- - nokia-restricted-pending
-
- Packages in nokia-restricted-pending are suitable for
- nokia-restricted that have not been published yet, similar to
- nokia-free-pending.
-
  - maemo.org-free
 
  Packages in maemo.org-free are Free Software.  They are licensed with a
@@ -178,10 +144,9 @@
  access this category freely.  Only people with a garage.maemo.org
  account can upload to it.
 
-The public categories starting with "nokia" are published on
-nokia.com.  The "maemo.org" categories are published on maemo.org.
+The categories starting with "nokia" are published on nokia.com.  The
+"maemo.org" categories are published on maemo.org.
 
-
 ** Distributions
 
 Most packages in the Maemo archive are part of one or more
@@ -195,17 +160,26 @@
 release them.  When copying packages, one or more source packages are
 copied together with all their binary packages.
 
-The distributions for Harmattan are "harmattan", "harmattan-testing",
- "harmattan-proposed-updates", and "harmattan-pending".
+The distributions for Harmattan are "harmattan-stable",
+"harmattan-testing", and "harmattan-proposed-updates".
 
 In detail:
 
- - harmattan
+ - harmattan-stable
 
- This distribution contains the current release of harmattan.  Devices
- of normal users use this distribution.  The *-pending categories of
- this distribution must always be empty.
+ This distribution contains the current release of Harmattan.  Devices
+ of normal users use this distribution.
 
+ Packages in harmattan-stable should be installable: all their
+ run-time dependencies should be available.
+
+ Packages in harmattan-stable should be rebuildable: all their build
+ dependencies should be available.
+
+ Only one version of a package can be in harmattan-stable.  If a new
+ version of a package enters harmattan-stable, the existing version is
+ removed.
+
  - harmattan-testing
 
  This distribution contains the current state of the upcoming release
@@ -213,54 +187,47 @@
  source packages.  Developers use this distribution in the SDK.  Beta
  testers use this distribution on their devices.
 
- The *-pending categories of this distribution must always be empty.
+ Packages in harmattan-testing don't need to be installable: it is OK
+ if dependencies are missing, just as it is OK to have other critical
+ bugs that prevent their release.
 
+ More than one version of a package can be in harmattan-testing.  See
+ the section "Expiration" below for how to keep the size of the Maemo
+ archive under control.
+
  - harmattan-proposed-updates
 
  This distribution is used to prepare small updates to packages in the
- harmattan distribution that can not wait until the package in
- harmattan-testing is of sufficient quality to be released.
+ harmattan-stable distribution that can not wait until the version of
+ the package in harmattan-testing is of sufficient quality to be
+ released.
 
  In other words, harmattan-proposed-updates is mainly for preparing
  security fixes.  It should be empty except for very short periods of
  time.
 
- The *-pending categories of this distribution must always be empty.
-
- - harmattan-pending
-
- This distribution is used to handle packages in the *-pending
- categories.  Source packages uploaded to (or redirected to) one of
- the *-pending categories are compiled in harmattan-testing +
- harmattan-pending.
-
- The harmattan-pending distribution should actively be kept small (by
- moving packages out of the *-pending categories) because it has a
- natural tendency to grow: once a package is in *-pending, it attracts
- more packages that depend on it.
-
 *** Compatibility
 
 Interface management will make the harmattan-testing distribution
-compatible with the harmattan distribution in a desired way.  Most
-packages compiled in harmattan-testing should be installable in
-harmattan.  Exceptions are allowed, but only by plan, not by accident.
-Compatibility requirements will be especially relaxed before the first
-release of harmattan.
+compatible with the harmattan-stable distribution in a desired way.
+Most packages compiled in harmattan-testing should be installable in
+harmattan-stable.  Exceptions are allowed, but only by plan, not by
+accident.  Compatibility requirements will be especially relaxed
+before the first release of Harmattan.
 
-Compatibility is important because packages (and groups of packages)
-are released independently.  Consider a typical 3rd party application
-in the extras category: they are meant to be installed 'immediately'
-on devices that run the current harmattan distribution.  They are not
-targeted at users running harmattan-testing, and they don't want to
-wait until their dependencies have been released.  Still, they are
-compiled in a harmattan-testing environment.
+Compatibility is important because groups of packages are released
+independently.  Consider a typical 3rd party application in the extras
+category: they are meant to be installed 'immediately' on devices that
+run the harmattan-stable distribution.  They are not targeted at users
+running harmattan-testing, and they don't want to wait until their
+dependencies have been released.  Still, they are compiled in a
+harmattan-testing environment.
 
 Problems with this will only arise when a binary package automatically
 picks up a incorrect run-time dependency that is not satisfiable in
-harmattan.  The correct dependency would be satisfiable in harmattan,
-but the build tools used to compute it did not produce the correct
-result.
+harmattan-stable.  The correct dependency would be satisfiable in
+harmattan-stable, but the build tools used to compute it did not
+produce the correct result.
 
 These problems need to be solved by simply computing the correct
 run-time dependencies during build time.
@@ -288,46 +255,53 @@
 *** Releasing
 
 Packages are released by copying them in groups from harmattan-testing
-to harmattan.  For a simple application in extras, this can be a
-single package, which is copied under control of the original
+to harmattan-stable.  For a simple application in extras, this can be
+a single package, which is copied under control of the original
 uploader.  For a big module like the OS, this will mean copying a huge
 set of packages under control of the release manager.
 
-When copying a group of packages in this way, the harmattan
+[ This is different from Debian, where the whole of testing is
+  released as a unit.  We don't do that since we want to release
+  'modules' independently.  See the "Configuration" section below.
+]
+
+When copying a group of packages in this way, the harmattan-stable
 distribution must not break, of course.  Most run-time and build-time
 dependencies between packages should still be satisfiable, and those
-that break should be identified and the breakage approved.
+that break should be identified and the breakage approved.  See the
+"Snapshots" section below for how to test whether harmattan-stable would
+break without actually running the risk of breaking it.
 
-[ Breaking harmattan might be considered OK when we release a OS
-  version that is incompatible with a 3rd party application.  Such an
-  application should ultimately not be able to delay the OS release.
-  This should be the exception and not the rule, of course.
+[ Breaking harmattan-stable might be considered OK when we release a
+  OS version that is incompatible with a 3rd party application.  Such
+  an application should ultimately not be able to delay the OS
+  release.  This should be the exception and not the rule, of course.
 ]
 
 Note that the SDK does not need to be released: harmattan-testing _is_
 the SDK distribution.  However, SDK packages should be copied to the
-harmattan distribution as well so that that distribution is always
-self-contained and recompilable.  This is part of the "do not break
-harmattan" rule: The harmattan distribution is also considered broken
-when its packages can not be recompiled.  This is important when using
-harmattan-proposed-updates for quick updates.
+harmattan-stable distribution as well so that that distribution is
+always self-contained and recompilable.  This is part of the "do not
+break harmattan-stable" rule: The harmattan-stable distribution is
+also considered broken when its packages can not be recompiled.  This
+is important when using harmattan-proposed-updates for urgent updates.
 
 *** Urgent updates
 
 The normal "Don't Panic" development process builds packages in
-harmattan-testing and slowly releases them to harmattan when they are
-ready.
+harmattan-testing and slowly releases them to harmattan-stable when
+they are ready.
 
 The "Panic Now" process for releasing security fixes and other urgent
 updates uses harmattan-proposed-updates in the following way.  The
 updated source package is uploaded to harmattan-proposed-updates and
-the responsible buildbot compiles it in a harmattan environment.  The
-update is tested by installing harmattan + harmattan-proposed-updates
-on a device.  If the update is considered releasable, the content of
-harmattan-proposed-updates is copied into harmattan and
-harmattan-proposed-updates is emptied.  If the update is not
-releasable, harmattan-proposed-updates is emptied as well, and the
-process starts over.
+the responsible buildbot compiles it in a harmattan-stable
+environment.  The update is tested by installing harmattan-stable +
+harmattan-proposed-updates on a device.  If the update is considered
+releasable, the content of harmattan-proposed-updates is copied into
+harmattan-stable and harmattan-proposed-updates is emptied.  If the
+update is not releasable, harmattan-proposed-updates is emptied as
+well, and the process starts over.
 
 It is important that harmattan-proposed-updates is almost always
 empty.  It would not be entirely inappropriate to send an email to
@@ -336,7 +310,7 @@
 
 *** Snapshots
 
-[...]
+[ The Maemo archive as a revision control system... ]
 
 *** Continuity
 
@@ -345,10 +319,54 @@
 
 When starting the "Isnogud" project (say), the isnogud,
 isnogud-testing, and isnogud-proposed-updates distributions are added
-to the Maemo archive.  They are created by copying the equivalent
+to the Maemo archive.  They are created by copying the corresponding
 Harmattan distributions.  Development then starts in isnogud-testing,
 without much regard to compatibility to isnogud if so desired.
 
+** Delayed publication
+
+The Maemo archive is public.  The Maemo system is developed and
+maintained in the open: this facilitates ad-hoc collaboration and
+other advantages of Open Source software development.
+
+However, packages can sometimes not be published immediately, although
+they eventually will be.  Reasons for holding back packages can be
+incomplete legal checks or the desire to keep them a trade secret
+until some launch event.
+
+Note also that delayed publishing is not strictly related to releasing
+a package.  Usually, packages should be published long before they are
+released.
+
+How packages are delayed is up to the party that desires it.  Inside
+Nokia, the Maemo archive is extended into the "Nokia archive" by
+adding three more categories: nokia-free-pending,
+nokia-non-free-pending, nokia-restricted-pending.  Packages in these
+categories are said to be "pending".
+
+The Nokia archive naturally contains the distributions of the Maemo
+archive.  However, those distributions must not have any packages in
+the three "*-pending" categories.  Thus, there is no way to upload a
+package into the "nokia-free-pending" category of the
+"harmattan-testing" distribution.
+
+Instead, the Nokia archive has one additional distribution:
+
+ - harmattan-pending
+
+ This distribution is used to handle packages in the *-pending
+ categories.  It consists of the packages in harmattan-testing plus
+ the pending packages.  Source packages uploaded to harmattan-pending
+ go to one of the *-pending categories and are compiled in
+ harmattan-pending.
+
+The infrastructure for the Maemo archive and the Nokia archive is
+separate: for example, the buildbots for the Maemo archive can only
+access publicly available sources.  When a pending package should
+finally be published, this has to be done by publishing the source and
+uploading it again to the Maemo archive (with an increased version
+number, of course).
+
 ** Repositories
 
 The Maemo archive is published in one or more "Repositories".  A