This is a tentative description of how the process for changing OpenSlug works.

When and where OpenSlug releases are made

This page describes OpenSlug releases and explains how the different locations of the OpenSlug source differ.

All OpenSlug versions are available in source form. The binary releases are built from the source - there's nothing hidden or binary only. The source can be found in two places:

1. http://monotone.nslu2-linux.org - this is the location of the monotone source database used for development. The database changes daily, even hourly.
2. http://www.slug-firmware.net - this is the location of the release source tarballs. These only change when a binary release is made and the previous tarballs are always available.

The three ways to get a working OpenSlug

The two source locations give two obvious ways to build OpenSlug. Building from the source tarball gives an OpenSlug identical to the corresponding binary release.

The third way of getting a working OpenSlug is to use ipkg upgrade to upgrade a release to the latest set of packages.

The monotone database

You must build from the source yourself. The result may not work - it may not work at all. After you have fixed any problems you should report the issues back to the #openslug IRC channel. You may also find that channel helpful in tracking down problems.

Ideally the monotone build should always:

1. Build openslug-packages successfully to completion.
2. Build an openslug-image which can boot to the point of permitting login via dropbear after a clean flash of the image.

This is all that can be expected of the monotone build. In particular packages in openslug-packages may not work even though they compile.

The release and source tarballs

The released binary is a snapshot, possibly with local fixes, of the monotone tree. It is expected to have the following properties:

1. It can be flashed to an NSLU2 and will boot successfully to the dropbear prompt.
2. It is possible to run turnup -i to initialise a fresh disk or fresh NFS partition and to boot into that disk.
3. It is possible to download and install any of the packages in the feed for the release - the stable feed, not the unstable feed.
4. The packages in the feed for the release install and work.

The last point is conditional on having adequate tests for the packages - in other words packages may have only received limited testing and bugs may show up with more advanced use.

There is no expectation that the packages listed in openslug-packages all work. Only the packages in the official feed are expected to work. The openslug-packages packages are expected to build, but that is all.

Upgrading from the package feed

The release or a source tarball build may be upgraded using ipk upgrade. So long as the upgrade uses the official, stable, feed - not the unstable feed - the result should still be fully functional.

An upgraded system does not change the flash image - it is, effectively, frozen at the original release. Repeating turnup -i will produce a new, release, system with no upgrades.

Upgrading from the feed is the expected method for all OpenSlug users to upgrade.

The development and release processes

The reason for documenting a "process" is that this makes it clear what changes go where and how to handle errors. The aim is to ensure that developers can make forward process without preventing the work of other developers and without harming user systems.

Developer changes

All developer changes are committed to the org.openembedded.dev branch of the monotone database. This development branch is shared with the rest of the OpenEmbedded developers, so be careful what you touch in it.

The unstable package feed is built from this branch and it is therefore only suitable for testing!

Changes checked in to the development branch should leave the branch with the following properties:

1. openslug-packages builds.
2. openslug-image builds and the result, if flashed into an NSLU2, will boot to the dropbear prompt on an unmodified NSLU2.
3. Changes to core OE packages either only change openslug or are made with the knowledge of the OE core developers. (Bumping the PR is ok.)

That is it.

Bumping the PR is very important If the PR is not bumped after a package change (any package change) there will be two versions of the package with the same version number. This must not happen with releases and should not happen in the monotone database. There are very few cases where it is ok not to increment the PR:

1. Spelling corrections in comments or other changes which have no effect on the package itself.
2. When a package is not being built by other developers (e.g. during the initial port, or when compilation is broken.)

Releases

Releases don't change. When a release is to be made the process is as follows:

1. A known monotone revision is used as the base.
2. The monotone revision is copied into the SVN release tree and any last minute patches made there - these patches will need to be separately applied (if necessary) to the monotone repository.

The development branch does not freeze during a release. If necessary a separate branch may be made.

The release package feed

Packages get incorporated into the feed from the monotone head. This is very similar to a release - a fixed monotone revision ID may be used for testing the relevant packages.

The package manager may also use a monotone branch to manage this process. After the SVN release has been made the original branch, if constructed, is not required, therefore the package manager can simply propagate changes from the development branch into the release branch as required.

Fixing problems

Changes will be committed which break booting or packages. Such changes need to be fixed in the correct place.

Unbootable systems

monotone changes which render stock systems unbootable should be fixed as soon as they are noticed. Responsbility for this relies with all the developers, regardless of who checked the change in.

It is reasonable to back out (monotone disapprove) a change if it is known to be the source of the problem. It is better to fix the problem.

If a change was really the wrong way to do something and if the right way wouldn't cause the problem disapproving the change is correct.

Broken package builds

If a change breaks a package build and the package is not required for openslug-image the package should be moved to the openslug-packages BROKEN_PACKAGES list and a bug-report should be sent to nslu2-linux mailinglist.

Broken packages

If a package builds but does not execute correctly a bug-report should be sent for the package.

This includes packages required by openslug-image so long as the system is bootable and a user/developer can log in via dropbear.