Update Development

Development.md

@@ -19,6 +19,33 @@ Upon reboot, the first system slot (Slot A) will generate its own verity partiti
 
 Eventually, this project will include an installation script that could be used from an Arch Linux or Alpine Linux minimal ISO.
 
+## OTA Updates
+
+HalogenOS OTA updates are designed to function regardless of who is building and distributing the OS. However, the URL scheme is important, as there are several components that might change in the future or gain additional variants (like the DE or the architecture).
+
+An example URL scheme might look like this:
+
+`https://example.com/halogenOS/$ARCH/$DE/`
+
+The `$ARCH` and `$DE` variables will remain as `x86_64` and `KDE` for the time being- they serve as placeholders for now.
+
+At the root of this directory, there must be a file titled `manifest.env`. It should define a few variables, like so:
+
+```
+ALPHA=2025091101
+BETA=2025091001
+STABLE=2025090801
+PUBKEY=somekeyname.pgp
+```
+
+If the distributor does not want to provide separate release channels, they must at least define a stable release entry which should point to the newest viable release. Stable is the default.
+
+If release signing is enabled, there must also be a valid PGP public key in that directory, which must correspond to the private key used to sign the release files. The release signing keys must never change, and HalogenOS build scripts must not be modified to allow the generation of images which would accept an update signed with a different public key than the one on-disk. The filename of the public key must correspond with the `PUBKEY` variable in the `manifest.env` file.
+
+Furthermore, the server must contain within that directory, a separate subdirectory for each release, with the directory name being the release number. Inside that directory should be two files:
+- A `.tar.gz` archive generated by the build script. The filename must be solely the version number and the `.tar.gz` extension.
+- A valid PGP signature of the tarball. The filename must be the name of the tarball file, appended with `.pgp`.
+
 ## Security
 
 Public-key cryptography is used to ensure that system images are not tampered with in transit, and to increase assurance that kernel modules are authorized to run on the system. The image distribution key must be consistent across releases, or else the system will be unable to update to any other version. Kernel keys should preferably remain the same across versions, but kernel modules must include their kernel target versions to ensure incorrect versions cannot be loaded.