ZX: Package and Submit a Project

Assuming your project is already listed on a Zomp realm somewhere, you will need to roll a new version of the package to submit for review on that realm. We must increment the version number to submit a new version of a package, of course, and the version levels Major/Minor/Patch must adhere to the semver recommendation lest you make your downstream users divide by zero and invite the return of Zuul and Gozer. If we are packaging a new minor version, for example, we need to increment the version number with "verup" and use the level "minor". Then we need to package the project with the "package" command.

If a Zomp/ZX project exists at the path provided a package file called "[realm_name]-[app_name]-[version].zsp" will be created in the current directory. This package bundle is already signed using your private user key for the relevant realm. If you have multiple keys you will be prompted to pick one.

Once packaged you need to submit your project. Submissions are only accepted from users with the "packager" role for the package on the hosting realm. If you are not already listed as a packager the sysop will need to grant you this permission. (It is not unusual for packagers and package maintainers to be different from the original author of a project.) To submit a project you need to use the "submit" command.

The process:

  1. Increase the version number at the appropriate level (if this hasn't already been done).
  2. Move to a working or temporary directory (we don't want to litter the project directory with packages).
  3. Submit it to the repo for review by a maintainer.
ceverett@takoyaki:~$ cd code/my_app
ceverett@takoyaki:~/code/my_app/$ zx verup minor
0.1.0 -> 0.2.0.
ceverett@takoyaki:~/code/my_app/$ cd ~
ceverett@takoyaki:~$ zx package code/my_app
Package signed and written to: ./my_realm-my_app-0.2.0.zsp
ceverett@takoyaki:~$ zx submit my_realm-my_app-0.2.0.zsp

The package will then be uploaded to the prime node for the realm and await review by a package maintainer. Once approved by a maintainer it will require a final resignature by the realm sysop before it is added to the realm's package index. You can check the current list of submitted but unreviewed packages with the "list pending" command, and check the current resign queue with the "list resigns" command.

After your initial submission:

ceverett@takoyaki:~$ zx list pending my_realm-my_app

And after a maintainer has approved the submission:

ceverett@takoyaki:~$ zx list approved my_realm

The above steps are the basics of how a developer/packager interacts with the system.

Keep in mind that while it is not unusual for a packager to be a maintainer or a maintainer to be a sysop, it is good practice to have at least two people involved in the chain of custody to minimize human error. That isn't always possible, but generally speaking the more eyes the better. When hosting code internally in a private realm with a small project team, of course, it is common for there to only be a single user in the system: the sysop.

The final step to making a package available on the system is to "accept" it. Only a sysop is able to perform the "accept" action, and it requires that the package be resigned (repackaged) by the sysop after "reviewing" it.

If we continue with the example above (my_realm-my_app-0.2.0) the sysop would unpack the approved code to review it locally:

ceverett@takoyaki:~/foo/$ zx review my_realm-my_app-0.2.0
ceverett@takoyaki:~/foo/$ ls
ceverett@takoyaki:~/foo/$ cd my_realm-my_app-0.2.0

After reviewing the package and deciding it should be accepted (be made publicly available) the sysop will re-pack the project (effectively re-signing it with the sysop key) and "accepting" it into the realm:

ceverett@takoyaki:~/foo/$ zx package my_realm-my_app-0.2.0/
Packaging my_realm-my_app-0.2.0/
Writing app file: ebin/my_app.app
Wrote archive my_realm-my_app-0.2.0.zsp
ceverett@takoyaki:~/foo/$ zx accept my_realm-my_app-0.2.0.zsp
ceverett@takoyaki:~/foo/$ zx list versions my_realm-my_app
ceverett@takoyaki:~/foo/$ rm -rf my_realm-my_app-0.2.0/