# PiDP-8/I Software Release Process

This documents the process for producing release versions of the
software.


## *Can* You Release Yet?

Before release, you must:

*   Fix all Immediate, High, and Medium priority [Bugs](/bugs)
*   Implement all Immediate and High priority [Features](/features)

Or reclassify them, of course.

Most of the bug levels simply aid scheduling: Immediate priority bugs
should be fixed before High, etc. Low priority bugs are “someone should
fix this someday” type of problems; these are the only ones allowed to
move from release to release. Think of bugs at this level as analogous
to the `BUGS` section of a Unix man page: our “low” intent to fix these
problems means they may stay at this level indefinitely, acting only as
advisories to the software’s users.

The Features levels may be read as:

*   **Immediate**: ASAP, or sooner. :)
*   **High**: Features for the upcoming release.
*   **Medium**: Features we’ll look at lifting to High for the release
    after that.
*   **Low**: “Wouldn’t it be nice if...”


## Update SIMH

If `tools/simh-update` hasn’t been run recently, you might want to do
that and re-test before publishing a new version.


## Test

1.  Build the software on the version of Raspberry Pi OS we’ll use for
    the binary OS image, [below](#image). Fix any problems.

2.  Run `make test` on the build host. Fix any problems.

3.  Repeat above on [all other platforms previously known to work][oscomp].
    Update the article to list caveats and such, or fix the problems.

(See “[How the PiDP-8/i Software Is Tested](./testing.md)” for details
on the philosophy and methods behind this process.)

[oscomp]: https://tangentsoft.com/pidp8i/wiki?name=OS+Compatibility


## Publish OS/8 RK05s

Re-configure the software with default settings, remove `bin/*.rk05`,
rebuild, and run `tools/publish-os8` to send the “final” OS/8 disk
images for this version of the software up to tangentsoft.com as
unversioned assets.

Update the date stamp in the “OS/8 RK05 Media” section of the project
home page.


## Update ChangeLog.md

Trawl the Fossil timeline for user-visible changes since the last
release, and write them up in user-focused form into [the `ChangeLog.md`
file][cl]. If a regular user of the software cannot see a given change,
it shouldn’t go in the `ChangeLog.md`; let it be documented via the
timeline only.

Immediately prior to release, `/doc`, `/dir`, `/file` and similar links
should point to trunk, but immediately prior to release, re-point them
to the `release` branch, since this document describes prior releases.

[cl]: https://tangentsoft.com/pidp8i/doc/trunk/ChangeLog.md


## Update the Release Branch

Run `make release` to check the `ChangeLog.md` file changes in, merge
trunk to the `release` branch, and apply a tag of the form vYYYYMMDD to
that merge checkin.

It runs entirely automatically unless an error occurs, in which case it
stops immediately, so check its output for errors before continuing.


## Update the Home Page Links

The zip and tarball links on the front page produce files named after
the date of the release. Those dates need to be updated immediately
after tagging the release, since they point at the “release” tag applied
by the previous step, so they begin shipping the new release immediately
after tagging it.


## <a id="image"></a>Produce the Binary OS Image

The binary OS image is built using [rpi-image-gen][rig] on a Raspberry
Pi 5 build host running the latest version of the Raspberry Pi OS.  This
replaces the [legacy `bosi` scheme](#legacy). See
`tools/pidp8i-image-gen/README.md` for background on the migration.

This process is restricted to 64-bit ARM targets.  It is therefore known
to work with the latest Pi 5 down to the Pi Zero 2 W.

### Prerequisites

*   A qualifying Raspberry Pi to use as a build host.  We recommend at
    least a Pi 4 to get decent build speed.  Alternatively,
    `rpi-image-gen` supports QEMU cross-builds on x86 and containerized
    builds, though these are not formally tested for PiDP-8/I images.

*   `rpi-image-gen` cloned to `~/rpi-image-gen`:

        $ cd ~
        $ git clone https://github.com/raspberrypi/rpi-image-gen

*   Required packages installed on the build host:

        $ cd ~/rpi-image-gen
        $ sudo ./install_deps.sh

*   The `pidp8i-image-gen` sub-tree synced to ~/pidp8i-image-gen on the Pi 5:

        $ rsync -av --delete ~/trunk/pidp8i-image-gen/ pi5:pidp8i-image-gen/

### Build the Image

On the Pi 5:

    $ cd ~/rpi-image-gen
    $ sudo ./rpi-image-gen build -S ~/pidp8i-image-gen -c pidp8i-trixie.yaml

The output image is written to `~/rpi-image-gen/work/deploy-<date>/pidp8i-trixie.img`.

To build for a different target device than the build host:

    $ sudo ./rpi-image-gen build -S ~/pidp8i-image-gen -c pidp8i-trixie.yaml \
        -- IGconf_device_layer=rpizero2w

### Test the Image

1.  Flash the image to a microSD card and boot it on a suitable target.
2.  [Edit the WiFi config][wifi] before first boot.
3.  On first boot the system will reboot automatically after installing
    the simulator service. After the second boot, the front panel lights
    should begin blinking.
4.  Verify SSH works: `ssh pidp8i@pidp8i.local`, implicitly testing the
    applied local WiFi configuration.
5.  Verify password change is forced on first login.
6.  Run `pidp8i` and confirm OS/8 is running.

[wifi]: ./OS-images.md#wifi

### Package the Release

Once testing is complete, create the release zip on the Mac:

    $ cd ~/rpi-image-gen/work/deploy-<date>/
    $ RELEASE=pidp8i-YYYY.MM.DD
    $ mkdir $RELEASE
    $ cp pidp8i-trixie.img $RELEASE/$RELEASE.img
    $ cp ~/trunk/doc/OS-images.md $RELEASE/README.md
    $ sha256sum $RELEASE/$RELEASE.img > $RELEASE/MANIFEST.txt
    $ zip -r $RELEASE.zip $RELEASE/
    $ scp $RELEASE.zip tangentsoft.com:dl/

Update the download links and image size on the project home page.


## <a id="legacy"></a>ARMv6 Images

The legacy [`bosi`](../tools/bosi) tool can
produce images for the 32-bit ARMv6 Pi boards (BCM2835), including the
original Raspberry Pi, the Pi 2, and the Pi Zero. This
platform is no longer supported by `rpi-image-gen`. The last images
produced this way were based on Raspberry Pi OS Buster (v10) Lite.

See the legacy build instructions in the `bosi` script itself for
the full procedure.


## Publicizing

While the image uploads, compose the announcement message and modify the
front page to point to the new image. Update the approximate image size
reported on that page. Post the announcement message and new front page
once the upload completes.


----------------------

### License

Copyright © 2016-2026 by Warren Young, Bill Cattey. This document is
licensed under the terms of [the SIMH license][sl].

[sl]: https://tangentsoft.com/pidp8i/doc/trunk/SIMH-LICENSE.md
[rig]: https://github.com/raspberrypi/rpi-image-gen
